From 5cb2edbad5d7eb551f8b53f12de893c719a25045 Mon Sep 17 00:00:00 2001 From: Melissa DeLucchi <113376043+delucchi-cmu@users.noreply.github.com> Date: Mon, 26 Feb 2024 13:58:04 -0500 Subject: [PATCH] Fix formatting in docstrings. (#222) --- .../partition_join_info.py | 9 +++--- .../healpix_dataset/healpix_dataset.py | 4 ++- src/hipscat/inspection/almanac_info.py | 4 +-- src/hipscat/io/file_io/file_io.py | 4 +-- src/hipscat/io/file_io/file_pointer.py | 28 ++++++++++++------- src/hipscat/io/paths.py | 18 ++++++------ src/hipscat/io/write_metadata.py | 15 ++++------ src/hipscat/pixel_math/margin_bounding.py | 4 +-- src/hipscat/pixel_math/pixel_margins.py | 25 +++++++++-------- src/hipscat/pixel_math/validators.py | 6 ++-- 10 files changed, 63 insertions(+), 54 deletions(-) diff --git a/src/hipscat/catalog/association_catalog/partition_join_info.py b/src/hipscat/catalog/association_catalog/partition_join_info.py index 31696998..c770a872 100644 --- a/src/hipscat/catalog/association_catalog/partition_join_info.py +++ b/src/hipscat/catalog/association_catalog/partition_join_info.py @@ -106,10 +106,11 @@ def write_to_metadata_files(self, catalog_path: FilePointer = None, storage_opti def write_to_csv(self, catalog_path: FilePointer = None, storage_options: dict = None): """Write all partition data to CSV files. - Two files will be written:: - - partition_info.csv - covers all primary catalog pixels, and should match the file structure - - partition_join_info.csv - covers all pairwise relationships between primary and - join catalogs. + Two files will be written: + + - partition_info.csv - covers all primary catalog pixels, and should match the file structure + - partition_join_info.csv - covers all pairwise relationships between primary and + join catalogs. Args: catalog_path: FilePointer to the directory where the diff --git a/src/hipscat/catalog/healpix_dataset/healpix_dataset.py b/src/hipscat/catalog/healpix_dataset/healpix_dataset.py index 3eb51bec..dffd4eed 100644 --- a/src/hipscat/catalog/healpix_dataset/healpix_dataset.py +++ b/src/hipscat/catalog/healpix_dataset/healpix_dataset.py @@ -17,7 +17,9 @@ class HealpixDataset(Dataset): """A HiPSCat dataset partitioned with a HEALPix partitioning structure. Catalogs of this type are partitioned based on the ra and dec of the points with each partition - containing points within a given HEALPix pixel. The files are in the form 'Norder=/Dir=/Npix=.parquet'. + containing points within a given HEALPix pixel. The files are in the form:: + + Norder=/Dir=/Npix=.parquet """ CatalogInfoClass: TypeAlias = BaseCatalogInfo diff --git a/src/hipscat/inspection/almanac_info.py b/src/hipscat/inspection/almanac_info.py index 750257c7..70cdc560 100644 --- a/src/hipscat/inspection/almanac_info.py +++ b/src/hipscat/inspection/almanac_info.py @@ -60,12 +60,12 @@ def get_default_dir() -> str: This is set via the environment variable: HIPSCAT_ALMANAC_DIR - To set this in a linux-like environment, use a command like: + To set this in a linux-like environment, use a command like:: export HIPSCAT_ALMANAC_DIR=/data/path/to/almanacs This will also attempt to expand any environment variables WITHIN the default - directory environment variable. This can be useful in cases where: + directory environment variable. This can be useful in cases where:: $HIPSCAT_ALMANAC_DIR=$HIPSCAT_DEFAULT_DIR/almanacs/ """ diff --git a/src/hipscat/io/file_io/file_io.py b/src/hipscat/io/file_io/file_io.py index 1d538cc0..51ea0686 100644 --- a/src/hipscat/io/file_io/file_io.py +++ b/src/hipscat/io/file_io/file_io.py @@ -270,8 +270,8 @@ def read_fits_image(map_file_pointer: FilePointer, storage_options: Union[Dict[A file_pointer: location of file to be written storage_options: dictionary that contains abstract filesystem credentials Returns: - histogram (:obj:`np.ndarray`): one-dimensional numpy array of long integers where the - value at each index corresponds to the number of objects found at the healpix pixel. + one-dimensional numpy array of long integers where the + value at each index corresponds to the number of objects found at the healpix pixel. """ file_system, map_file_pointer = get_fs(file_pointer=map_file_pointer, storage_options=storage_options) with tempfile.NamedTemporaryFile() as _tmp_file: diff --git a/src/hipscat/io/file_io/file_pointer.py b/src/hipscat/io/file_io/file_pointer.py index ea978a6b..4b1c58c9 100644 --- a/src/hipscat/io/file_io/file_pointer.py +++ b/src/hipscat/io/file_io/file_pointer.py @@ -9,8 +9,8 @@ def get_file_protocol(pointer: FilePointer) -> str: """Method to parse filepointer for the filesystem protocol. - if it doesn't follow the pattern of protocol://pathway/to/file, then it - assumes that it is a localfilesystem. + If it doesn't follow the pattern of protocol://pathway/to/file, then it + assumes that it is a localfilesystem. Args: pointer: filesystem pathway pointer @@ -33,7 +33,7 @@ def get_fs( file_pointer: filesystem pathway storage_options: dictionary that contains abstract filesystem credentials Raises: - ImportError if environment cannot import necessary libraries for + ImportError: if environment cannot import necessary libraries for fsspec filesystems. """ if storage_options is None: @@ -50,15 +50,17 @@ def get_fs( def get_file_pointer_for_fs(protocol: str, file_pointer: FilePointer) -> FilePointer: - """Creates the filepathway from the file_pointer. Will strip the protocol so that - the file_pointer can be accessed from the filesystem - abfs filesystems DO NOT require the account_name in the pathway - s3 filesystems DO require the account_name/container name in the pathway + """Creates the filepathway from the file_pointer. + + This will strip the protocol so that the file_pointer can be accessed from + the filesystem: + + - abfs filesystems DO NOT require the account_name in the pathway + - s3 filesystems DO require the account_name/container name in the pathway Args: protocol: str filesytem protocol, file, abfs, or s3 file_pointer: filesystem pathway - """ if not isinstance(file_pointer, str): file_pointer = str(file_pointer) @@ -105,7 +107,13 @@ def get_basename_from_filepointer(pointer: FilePointer) -> str: def strip_leading_slash_for_pyarrow(pointer: FilePointer, protocol: str) -> FilePointer: """Strips the leading slash for pyarrow read/write functions. - This is required for their filesystem abstraction + This is required for pyarrow's underlying filesystem abstraction. + + Args: + pointer: `FilePointer` object + + Returns: + New file pointer with leading slash removed. """ if protocol != "file" and str(pointer).startswith("/"): pointer = FilePointer(str(pointer).replace("/", "", 1)) @@ -203,7 +211,7 @@ def get_directory_contents( ) -> List[FilePointer]: """Finds all files and directories in the specified directory. - NBL This is not recursive, and will return only the first level of directory contents. + NB: This is not recursive, and will return only the first level of directory contents. Args: pointer: File Pointer in which to find contents diff --git a/src/hipscat/io/paths.py b/src/hipscat/io/paths.py index 7d2c074e..a78329af 100644 --- a/src/hipscat/io/paths.py +++ b/src/hipscat/io/paths.py @@ -32,11 +32,11 @@ def pixel_directory( """Create path pointer for a pixel directory. This will not create the directory. One of pixel_number or directory_number is required. The directory name will - take the HiPS standard form of: + take the HiPS standard form of:: /Norder=/Dir= - Where the directory number is calculated using integer division as: + Where the directory number is calculated using integer division as:: (pixel_number/10000)*10000 @@ -64,7 +64,8 @@ def pixel_directory( def get_healpix_from_path(path: str) -> HealpixPixel: - """Find the `pixel_order` and `pixel_number` from a string like the following:: + """Find the `pixel_order` and `pixel_number` from a string like the + following:: Norder=/Dir=/Npix=.parquet @@ -85,13 +86,14 @@ def get_healpix_from_path(path: str) -> HealpixPixel: def pixel_catalog_file(catalog_base_dir: FilePointer, pixel_order: int, pixel_number: int) -> FilePointer: - """Create path *pointer* for a pixel catalog file. This will not create the directory or file. + """Create path *pointer* for a pixel catalog file. This will not create the directory + or file. - The catalog file name will take the HiPS standard form of: + The catalog file name will take the HiPS standard form of:: /Norder=/Dir=/Npix=.parquet - Where the directory number is calculated using integer division as: + Where the directory number is calculated using integer division as:: (pixel_number/10000)*10000 @@ -113,7 +115,7 @@ def create_hive_directory_name(base_dir, partition_token_names, partition_token_ """Create path *pointer* for a directory with hive partitioning naming. This will not create the directory. - The directory name will have the form of: + The directory name will have the form of:: /=/.../= @@ -132,7 +134,7 @@ def create_hive_directory_name(base_dir, partition_token_names, partition_token_ def create_hive_parquet_file_name(base_dir, partition_token_names, partition_token_values): """Create path *pointer* for a single parquet with hive partitioning naming. - The file name will have the form of: + The file name will have the form of:: /=/.../=.parquet diff --git a/src/hipscat/io/write_metadata.py b/src/hipscat/io/write_metadata.py index 91c86958..eb91f925 100644 --- a/src/hipscat/io/write_metadata.py +++ b/src/hipscat/io/write_metadata.py @@ -94,8 +94,10 @@ def write_partition_info( catalog_base_dir (str): base directory for catalog, where file will be written destination_healpix_pixel_map (dict): dictionary that maps the HealpixPixel to a tuple of origin pixel information: - - 0 - the total number of rows found in this destination pixel - - 1 - the set of indexes in histogram for the pixels at the original healpix order + + - 0 - the total number of rows found in this destination pixel + - 1 - the set of indexes in histogram for the pixels at the original healpix order + storage_options: dictionary that contains abstract filesystem credentials """ partition_info_pointer = paths.get_partition_info_pointer(catalog_base_dir) @@ -109,14 +111,7 @@ def write_partition_info( data_frame["Dir"] = [int(x / 10_000) * 10_000 for x in data_frame["Npix"]] # Reorder the columns to match full path, and force to integer types. - data_frame = data_frame[ - [ - "Norder", - "Dir", - "Npix", - "num_rows", - ] - ].astype(int) + data_frame = data_frame[["Norder", "Dir", "Npix", "num_rows"]].astype(int) file_io.write_dataframe_to_csv( data_frame, partition_info_pointer, index=False, storage_options=storage_options diff --git a/src/hipscat/pixel_math/margin_bounding.py b/src/hipscat/pixel_math/margin_bounding.py index a87dbc53..ec4786f0 100644 --- a/src/hipscat/pixel_math/margin_bounding.py +++ b/src/hipscat/pixel_math/margin_bounding.py @@ -30,8 +30,8 @@ def check_margin_bounds(r_asc, dec, pixel_order, pixel, margin_threshold, step=1 memory issues. Returns: :obj:`numpy.array` of boolean values corresponding to the ra and dec - coordinates checked against whether a given point is within any of the - provided polygons. + coordinates checked against whether a given point is within any of the + provided polygons. """ num_points = len(r_asc) if num_points != len(dec): diff --git a/src/hipscat/pixel_math/pixel_margins.py b/src/hipscat/pixel_math/pixel_margins.py index 9bd93543..6f902025 100644 --- a/src/hipscat/pixel_math/pixel_margins.py +++ b/src/hipscat/pixel_math/pixel_margins.py @@ -27,17 +27,18 @@ def get_edge(d_order, pix, edge): dk (int): the change in k that we wish to find the margins for. pix (int): the healpix pixel to find margin pixels of. edge (int): the edge we want to find for the given pixel. (0-7) - 0: NE edge - 1: E corner - 2: SE edge - 3: S corner - 4: SW edge - 5: W corner - 6: NW edge - 7: N corner + + - 0: NE edge + - 1: E corner + - 2: SE edge + - 3: S corner + - 4: SW edge + - 5: W corner + - 6: NW edge + - 7: N corner Returns: one-dimensional numpy array of long integers, filled with the healpix pixels - at order kk+dk that border the given edge of pix. + at order kk+dk that border the given edge of pix. """ if edge < 0 or edge > 7: raise ValueError("edge can only be values between 0 and 7 (see docstring)") @@ -74,7 +75,7 @@ def get_margin(order, pix, d_order): Must be greater than kk. Returns: one-dimensional numpy array of long integers, filled with the healpix pixels - at order kk+dk that border pix. + at order kk+dk that border pix. """ if d_order < 1: raise ValueError("dk must be greater than order") @@ -122,8 +123,8 @@ def pixel_is_polar(order, pix): pix (int): the id of a healpixel to be checked. must be in the nested id scheme. Returns: tuple of a boolean and a string, the boolean indicating whether the pixel - polar and the string denoting which pole it is ('North' or 'South')). - string is empty in the case that the pixel isn't polar. + polar and the string denoting which pole it is ('North' or 'South')). + string is empty in the case that the pixel isn't polar. """ nside = hp.order2nside(order) npix = hp.nside2npix(nside) diff --git a/src/hipscat/pixel_math/validators.py b/src/hipscat/pixel_math/validators.py index 6f9cf870..77d9c8a5 100644 --- a/src/hipscat/pixel_math/validators.py +++ b/src/hipscat/pixel_math/validators.py @@ -24,7 +24,7 @@ def validate_radius(radius_arcsec: float): radius_arcsec (float): The cone radius, in arcseconds Raises: - ValueError if radius is non-positive + ValueError: if radius is non-positive """ if radius_arcsec <= 0: raise ValueError(ValidatorsErrors.INVALID_RADIUS.value) @@ -37,7 +37,7 @@ def validate_declination_values(dec: float | List[float]): dec (float | List[float]): The declination values to be validated Raises: - ValueError if declination values are not in the [-90,90] degree range + ValueError: if declination values are not in the [-90,90] degree range """ dec_values = np.array(dec) lower_bound, upper_bound = -90.0, 90.0 @@ -53,7 +53,7 @@ def validate_polygon(vertices: np.ndarray): vertices (np.ndarray): The polygon vertices, in cartesian coordinates Raises: - ValueError exception if the polygon is invalid. + ValueError: exception if the polygon is invalid. """ if len(vertices) < 3: raise ValueError(ValidatorsErrors.INVALID_NUM_VERTICES.value)