From 4614c3f4feddc9b8e31f31cee470ccc93b266593 Mon Sep 17 00:00:00 2001 From: mscheltienne Date: Mon, 22 Jul 2024 13:35:22 +0200 Subject: [PATCH] fix a bunch of numpydoc violations --- nigsp/blocks.py | 21 +++---- nigsp/io.py | 147 +++++++++++++++++++++--------------------------- nigsp/viz.py | 6 +- 3 files changed, 76 insertions(+), 98 deletions(-) diff --git a/nigsp/blocks.py b/nigsp/blocks.py index 45a01e2..6bb7bea 100644 --- a/nigsp/blocks.py +++ b/nigsp/blocks.py @@ -17,14 +17,13 @@ def nifti_to_timeseries(fname, atlasname): - """ - Read a nifti file and returns a normalised timeseries from an atlas. + """Read a nifti file and returns a normalised timeseries from an atlas. Parameters ---------- - fname : string or os.PathLike + fname : str | os.PathLike Filename (and path) of a functional timeseries nifti dataset. - atlasname : string or os.PathLike + atlasname : str | os.PathLike Filename (and path) of an atlas nifti dataset. Returns @@ -49,8 +48,7 @@ def nifti_to_timeseries(fname, atlasname): def export_metric(scgraph, outext, outprefix): - """ - Export the metrics computed within the library. + """Export the metrics computed within the library. Parameters ---------- @@ -64,7 +62,7 @@ def export_metric(scgraph, outext, outprefix): Returns ------- 0 - If everything goes well + If everything goes well. """ if outext in io.EXT_NIFTI: try: @@ -100,17 +98,16 @@ def export_metric(scgraph, outext, outprefix): def plot_metric(scgraph, outprefix, atlas=None, thr=None): - """ - If possible, plot metrics as markerplot. + """If possible, plot metrics as markerplot. Parameters ---------- scgraph : SCGraph object The internal object containing all data. outprefix : str - The prefix of the png file to export - img : 3DNiftiImage or None, optional - The nifti image of the atlas + The prefix of the png file to export. + img : 3DNiftiImage | None + The nifti image of the atlas. atlas : 3D Nifti1Image, numpy.ndarray, or None, optional Either a nifti image containing a valid atlas or a set of parcel coordinates. thr : float or None, optional diff --git a/nigsp/io.py b/nigsp/io.py index c27c8f3..e43e742 100644 --- a/nigsp/io.py +++ b/nigsp/io.py @@ -40,31 +40,30 @@ def check_ext(all_ext, fname, scan=False, remove=False): - """ - Check which extension a file has, and possibly remove it. + """Check which extension a file has, and possibly remove it. Parameters ---------- all_ext : list - All possible extensions to check within + All possible extensions to check within. fname : str or os.PathLike - The filename to check + The filename to check. scan : bool, optional Scan the given path to see if there is a file with that extension If True and no path declared, check if fname has a path, if not scan '.' - If False, don't scan any folder + If False, don't scan any folder. remove : bool, optional - Remove the extension from fname if it has one + Remove the extension from fname if it has one. Returns ------- obj_return : Uses a list to return variable amount of options. has_ext : boolean - True if the extension is found, false otherwise + True if the extension is found, false otherwise. fname : str or os.PathLike - If `remove` is True, return (extensionless) fname + If ``remove`` is True, return (extensionless) fname. ext : str - If both `remove` and `has_ext` are True, returns also found extension + If both ``remove`` and ``has_ext`` are True, returns also found extension. """ has_ext = False all_ext = change_var_type(all_ext, list, stop=False, silent=True) @@ -96,67 +95,65 @@ def check_ext(all_ext, fname, scan=False, remove=False): def check_nifti_dim(fname, data, dim=4): - """ - Check number of dimensions in nifti file. + """Check number of dimensions in nifti file. Parameters ---------- fname : str - The name of the file representing `data` + The name of the file representing ``data``. data : numpy.ndarray - The data which dimensionality needs to be checked + The data which dimensionality needs to be checked. dim : int, optional The amount of dimensions expected/desired in the data. Returns ------- numpy.ndarray - If `data.ndim` = `dim`, returns data. + If ``data.ndim = dim``, returns data. Raises ------ ValueError - If `data` has different dimensions than `dim` + If ``data`` has different dimensions than ``dim``. """ data = data.squeeze() if data.ndim != dim: raise ValueError( - f"A {dim}D nifti file is required, but {fname} is " - f"{data.ndim}D. Please check the input file." + f"A {dim}D nifti file is required, but {fname} is {data.ndim}D. Please " + "check the input file." ) return data def check_mtx_dim(fname, data, shape=None): - """ - Check dimensions of a matrix. + """Check dimensions of a matrix. Parameters ---------- fname : str - The name of the file representing `data` + The name of the file representing ``data``. data : np.ndarray - The data which dimensionality needs to be checked - shape : None, 'square', or 'rectangle'}, str, optional - Shape of matrix, if empty, skip shape check + The data which dimensionality needs to be checked. + shape : None | ``'square'`` | ``'rectangle'`` + Shape of matrix, if empty, skip shape check. Returns ------- np.ndarray - If `data.ndim` = 2, returns data. - If `data.ndim` = 1 and `shape` == 'rectangle', - Returns data with added empty axis. + If ``data.ndim = 2``, returns data. + If ``data.ndim = 1`` and ``shape == 'rectangle'``, returns data with added empty + axis. Raises ------ NotImplementedError - If `data` has more than 3 dimensions. - If `shape` is not None but `data` is 3D. + If ``data`` has more than 3 dimensions. + If ``shape`` is not None but `data` is 3D. ValueError - If `data` is empty - If `shape` == 'square' and `data` dimensions have different lengths. + If ``data`` is empty + If ``shape == 'square'`` and ``data`` dimensions have different lengths. """ data = data.squeeze() LGR.info("Checking data shape.") @@ -187,19 +184,17 @@ def check_mtx_dim(fname, data, shape=None): def load_nifti_get_mask(fname, is_mask=False, ndim=4): - """ - Load a nifti file and returns its data, its image, and a 3d mask. + """Load a nifti file and returns its data, its image, and a 3D mask. Parameters ---------- fname : str - The filename to read in + The filename to read in. is_mask : bool, optional - If the file contains a mask. - Default: False + If the file contains a mask. Default to ``False``. ndim : int or None, optional The number of dimensions expected in the data. - If None (default), 4 dimensions are expected, unless is_mask=True. + If None (default), 4 dimensions are expected, unless ``is_mask=True``. In the latter case, 3 dimensions will be checked. Returns @@ -207,10 +202,10 @@ def load_nifti_get_mask(fname, is_mask=False, ndim=4): data : numpy.ndarray Data from nifti file. mask : numpy.ndarray - If `is_mask` is False, numpy.ndarray of one dimension less than data, + If ``is_mask`` is ``False``, numpy.ndarray of one dimension less than data, in which any element that has at least a value different from zero - in the last dimension of `data` is True. - If `is_mask` is True, mask is a boolean representation of data. + in the last dimension of ``data`` is True. + If ``is_mask`` is ``True``, mask is a boolean representation of data. img : nib.img Image object from nibabel. @@ -219,8 +214,8 @@ def load_nifti_get_mask(fname, is_mask=False, ndim=4): import nibabel as nib except ImportError: raise ImportError( - "nibabel is required to import nifti files. " - "Please see install instructions." + "nibabel is required to import nifti files. Please see install " + "instructions." ) LGR.info(f"Loading {fname}.") @@ -243,20 +238,19 @@ def load_nifti_get_mask(fname, is_mask=False, ndim=4): def load_txt(fname, shape=None): - """ - Read files in textual format. + """Read files in textual format. Parameters ---------- - fname : str or os.PathLike - Path to the txt file - shape : None, 'square', or 'rectangle', optional - Shape of matrix, if empty, skip check + fname : str | os.PathLike + Path to the txt file. + shape : None | ``'square'`` | ``'rectangle'`` + Shape of matrix, if empty, skip check. Returns ------- mtx : numpy.ndarray - Data matrix + Data matrix. See also -------- @@ -283,8 +277,7 @@ def load_txt(fname, shape=None): def load_mat(fname, shape=None): - """ - Read files in matlab format. + """Read files in MATLAB format. Assumes the existence of a matrix/vector in the mat file, rendered as a numpy.ndarray. If there is more than a matrix, the one with the largest @@ -292,19 +285,19 @@ def load_mat(fname, shape=None): Parameters ---------- - fname : str or os.PathLike - Path to the mat file - shape : None, 'square', or 'rectangle'}, str, optional - Shape of matrix, if empty, skip check + fname : str | os.PathLike + Path to the ``.mat`` file. + shape : None | ``'square'`` | ``'rectangle'`` + Shape of matrix, if empty, skip check. Returns ------- mtx : numpy.ndarray - Data matrix + Data matrix. Notes ----- - Requires module pymatreader to work + Requires module ``pymatreader`` to work. See also -------- @@ -361,19 +354,14 @@ def load_mat(fname, shape=None): def load_xls(fname, shape=""): - """ - Read files in xls format. + """Read files in xls format. Parameters ---------- - fname : str or os.PathLike - Path to the mat file - shape : None, 'square', or 'rectangle'}, str, optional - Shape of matrix, if empty, skip check - - Notes - ----- - Requires module _ to work + fname : str | os.PathLike + Path to the xls file. + shape : None | ``'square'`` | ``'rectangle'`` + Shape of matrix, if empty, skip check. See also -------- @@ -388,41 +376,35 @@ def load_xls(fname, shape=""): def export_nifti(data, img, fname): - """ - Export a nifti file. + """Export a nifti file. Parameters ---------- data : numpy.ndarray - Data to be exported + Data to be exported. img : nib.img - Nibabel image object - fname : str or os.PathLike - Name of the output file + Nibabel image object. + fname : str | os.PathLike + Name of the output file. """ try: import nibabel as nib except ImportError: raise ImportError( - "nibabel is required to export nifti files. " - "Please see install instructions." + "nibabel is required to export nifti files. Please see install " + "instructions." ) - has_ext, fname, ext = check_ext(EXT_NIFTI, fname, remove=True) - if ext is None: ext = ".nii.gz" - LGR.info(f"Exporting nifti data into {fname}{ext}.") out_img = nib.Nifti1Image(data, img.affine, img.header) out_img.to_filename(f"{fname}{ext}") - return 0 def export_txt(data, fname, ext=None): - """ - Export data into a text-like or mat file. + """Export data into a text-like or mat file. Parameters ---------- @@ -478,14 +460,13 @@ def export_txt(data, fname, ext=None): def export_mtx(data, fname, ext=None): - """ - Export data into a text-like or mat file. + """Export data into a text-like or mat file. Parameters ---------- data : np.ndarray Data to be exported. - fname : str or os.PathLike + fname : str | os.PathLike Name of the output file. ext : str or None, optional Selected extension for export. diff --git a/nigsp/viz.py b/nigsp/viz.py index 4ddb65d..56811ac 100644 --- a/nigsp/viz.py +++ b/nigsp/viz.py @@ -275,14 +275,14 @@ def plot_edges(mtx, atlas, filename=None, thr=None, closeplot=False): ---------- mtx : numpy.ndarray A 2- or 3- D array that contains the value of the nodes. - atlas : str, os.PathLike, 3D Nifti1Image, or numpy.ndarray + atlas : str | os.PathLike | 3D Nifti1Image | numpy.ndarray The 3d nifti image of an atlas, a string or path to its position, or a list of coordinates of the center of mass of parcels. filename : None, str, or os.PathLike, optional The path to save the plot on disk. thr : float, str or None, optional The threshold to use in plotting the nodes. - If `str`, needs to express a percentage. + If :class:``str``, needs to express a percentage. closeplot : bool, optional Whether to close plots after saving or not. Mainly used for debug or use with live python/ipython instances. @@ -302,7 +302,7 @@ def plot_edges(mtx, atlas, filename=None, thr=None, closeplot=False): Notes ----- - Requires `matplotlib` and `nilearn` + Requires ``matplotlib`` and ``nilearn``. """ try: import matplotlib.pyplot as plt