From 17e5ebc6d968b3dcb90e3333b5c7b2883bb25afc Mon Sep 17 00:00:00 2001 From: Kimberly Meechan <24316371+K-Meech@users.noreply.github.com> Date: Tue, 9 Apr 2024 12:30:58 +0100 Subject: [PATCH] Convert remaining docstrings to numpydoc style (#66) * convert remaining docstrings to numpydoc style * Expand docstring of safe_pandas_concat Co-authored-by: Will Graham <32364977+willGraham01@users.noreply.github.com> * fix line length --------- Co-authored-by: Will Graham <32364977+willGraham01@users.noreply.github.com> --- brainglobe_utils/image/binning.py | 18 +++++--- brainglobe_utils/image/masking.py | 39 ++++++++++++----- brainglobe_utils/image/scale.py | 24 ++++++++--- brainglobe_utils/pandas/misc.py | 47 ++++++++++++++++----- tests/tests/test_brainreg/test_transform.py | 11 +++-- 5 files changed, 102 insertions(+), 37 deletions(-) diff --git a/brainglobe_utils/image/binning.py b/brainglobe_utils/image/binning.py index ba015fd..2933369 100644 --- a/brainglobe_utils/image/binning.py +++ b/brainglobe_utils/image/binning.py @@ -3,11 +3,19 @@ def get_bins(image_size, bin_sizes): """ - Given an image size, and bin size, return a list of the bin boundaries - :param image_size: Size of the final image (tuple/list) - :param bin_sizes: Bin sizes corresponding to the dimensions of - "image_size" (tuple/list) - :return: List of arrays of bin boundaries + Given an image size, and bin size, return a list of the bin boundaries. + + Parameters + ---------- + image_size : tuple of int or list of int + Size of the final image + bin_sizes : tuple of int or list of int + Bin sizes corresponding to the dimensions of "image_size" + + Returns + ------- + list of np.ndarray + List of arrays of bin boundaries """ bins = [] for dim in range(0, len(image_size)): diff --git a/brainglobe_utils/image/masking.py b/brainglobe_utils/image/masking.py index 73d4a4b..5df6372 100644 --- a/brainglobe_utils/image/masking.py +++ b/brainglobe_utils/image/masking.py @@ -4,11 +4,21 @@ def mask_image_threshold(image, masking_image, threshold=0): """ Mask one image, based on the values in another image that are above a - threshold - :param image: Input image - :param masking_image: Image to base the mask on (same shape as image) - :param threshold: Threshold to base the mask on - :return: Masked image + threshold. + + Parameters + ---------- + image : np.ndarray + Input image + masking_image : np.ndarray + Image to base the mask on (same shape as image) + threshold : int, optional + Threshold to base the mask on + + Returns + ------- + np.ndarray + Masked image """ masking_image = make_mask(masking_image, threshold=threshold) return image * masking_image @@ -17,11 +27,20 @@ def mask_image_threshold(image, masking_image, threshold=0): def make_mask(masking_image, threshold=0): """ Given an image, and an optional threshold, returns a binary image that can - be used as a mask - :param masking_image: nD image - :param threshold: Optional threshold, default 0. Values above this are - included in the mask. Values below this are not. - :return: Binary mask + be used as a mask. + + Parameters + ---------- + masking_image : np.ndarray + nD image + threshold : int, optional + Optional threshold, default 0. Values above this are + included in the mask. Values below this are not. + + Returns + ------- + np.ndarray + Binary mask """ mask = np.copy(masking_image) mask[masking_image <= threshold] = 0 diff --git a/brainglobe_utils/image/scale.py b/brainglobe_utils/image/scale.py index 824dfca..fff7e85 100644 --- a/brainglobe_utils/image/scale.py +++ b/brainglobe_utils/image/scale.py @@ -5,9 +5,15 @@ def scale_to_16_bits(img): """ Normalise the input image to the full 0-2^16 bit depth. - :param np.array img: The input image - :return: The normalised image - :rtype: np.array + Parameters + ---------- + img : np.ndarray + The input image + + Returns + ------- + np.ndarray + The normalised image """ normalised = img / img.max() return normalised * (2**16 - 1) @@ -18,9 +24,15 @@ def scale_and_convert_to_16_bits(img): Normalise the input image to the full 0-2^16 bit depth, and return as type: "np.uint16". - :param np.array img: The input image - :return: The normalised, 16 bit image - :rtype: np.array + Parameters + ---------- + img : np.ndarray + The input image + + Returns + ------- + np.ndarray + The normalised, 16 bit image """ img = scale_to_16_bits(img) return img.astype(np.uint16, copy=False) diff --git a/brainglobe_utils/pandas/misc.py b/brainglobe_utils/pandas/misc.py index 5bfe673..2758e56 100644 --- a/brainglobe_utils/pandas/misc.py +++ b/brainglobe_utils/pandas/misc.py @@ -4,18 +4,34 @@ def initialise_df(*column_names): """ - Initialise a pandasdataframe with n column names - :param str column_names: N column names - :return: Empty pandas dataframe with specified column names + Initialise a pandas dataframe with n column names. + + Parameters + ---------- + *column_names : str + N column names + + Returns + ------- + pd.DataFrame + Empty pandas dataframe with specified column names """ return pd.DataFrame(columns=column_names) def sanitise_df(df): """ - Replaces infinite values in a dataframe with NaN - :param df: Any dataframe - :return: Dataframe with Inf replaced with NaN + Replaces infinite values in a dataframe with NaN. + + Parameters + ---------- + df : pd.DataFrame + Any dataframe + + Returns + ------- + pd.DataFrame + Dataframe with Inf replaced with NaN. """ df = df.replace(np.inf, np.nan) return df @@ -25,14 +41,25 @@ def safe_pandas_concat(df1: pd.DataFrame, df2: pd.DataFrame) -> pd.DataFrame: """ Concatenate two DataFrames without relying on deprecated functionality when one of the DataFrames is empty. - If df1 and df2 are non-empty, return the concatenation. + + If df1 and df2 are non-empty, return the concatenation. df2 will extend df1 + in the resulting DataFrame. If df1 is empty and df2 is not, return a copy of df2. If df1 is non-empty and df2 is, return a copy of df1. If df1 and df2 are empty, return an empty DataFrame with the same column names as df1. - :param df1: DataFrame to concatenate. - :param df2: DataFrame to concatenate. - :returns: DataFrame formed from concatenation of df1 and df2. + + Parameters + ---------- + df1 : pd.DataFrame + DataFrame to concatenate. + df2 : pd.DataFrame + DataFrame to concatenate. + + Returns + ------- + pd.DataFrame + DataFrame formed from concatenation of df1 and df2. """ if df1.empty and df2.empty: return pd.DataFrame(columns=df1.columns) diff --git a/tests/tests/test_brainreg/test_transform.py b/tests/tests/test_brainreg/test_transform.py index 43eaaac..7a407c2 100644 --- a/tests/tests/test_brainreg/test_transform.py +++ b/tests/tests/test_brainreg/test_transform.py @@ -31,12 +31,11 @@ def test_transform_points_from_downsampled_to_atlas_space( * check that deformation field of ones maps to 1,1,1*resolution * check that too small deformation field maps points to out-of-bounds - Args: - mocker: The mocker object used to patch the reading of deformation - field tiffs. - - Returns: - None + Parameters + ---------- + mocker : pytest_mock.plugin.MockerFixture + The mocker object used to patch the reading of deformation + field tiffs. """ mocker.patch( "brainglobe_utils.brainreg.transform.tifffile.imread",