From 8a5510206ab1680d1ae8ff6f61e957dd91eaa6da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 18:52:16 -0400 Subject: [PATCH 01/10] DOC: Fix typos and grammar Fix typos and grammar. --- dipy/align/imaffine.py | 2 +- dipy/reconst/fwdti.py | 2 +- dipy/segment/bundles.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/dipy/align/imaffine.py b/dipy/align/imaffine.py index bff198d07a..5809fa9276 100644 --- a/dipy/align/imaffine.py +++ b/dipy/align/imaffine.py @@ -110,7 +110,7 @@ def __init__( sampling information needs to be specified each time the `transform` or `transform_inverse` is called to transform images. Note that such sampling information is not necessary to transform points defined in - physical space, such as stream lines. + physical space, such as streamlines. Parameters ---------- diff --git a/dipy/reconst/fwdti.py b/dipy/reconst/fwdti.py index 7f188effaf..657a6737d8 100644 --- a/dipy/reconst/fwdti.py +++ b/dipy/reconst/fwdti.py @@ -314,7 +314,7 @@ def wls_iter( FS, SI = np.meshgrid(fs, sig) SA = SI - FS * S0 * SFW.T # SA < 0 means that the signal components from the free water - # component is larger than the total fiber. This cases are present + # component is larger than the total fiber. These cases are present # for inappropriate large volume fractions (given the current S0 # value estimated). To overcome this issue negative SA are replaced # by data's min positive signal. diff --git a/dipy/segment/bundles.py b/dipy/segment/bundles.py index dff54c4b56..79d0077189 100644 --- a/dipy/segment/bundles.py +++ b/dipy/segment/bundles.py @@ -412,7 +412,7 @@ def recognize( slr_bounds : array, optional (default None) slr_select : tuple, optional - Select the number of streamlines from model to neirborhood of + Select the number of streamlines from model to neighborhood of model to perform the local SLR. slr_method : string, optional Optimization method 'L_BFGS_B' or 'Powell' optimizers can be used. From 3513106230eb2da5d2894f3029f287953c6c96f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:03:40 -0400 Subject: [PATCH 02/10] DOC: Format properly returned parameter docstrings Format properly returned parameter docstrings following the `numpydoc` convention: - Make each parameter have its own docstring. - Make the parameter name and type dwell on a line, and start the corresponding description on a separate line. --- dipy/align/_public.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/dipy/align/_public.py b/dipy/align/_public.py index bc6903fdc6..95dd5b853e 100644 --- a/dipy/align/_public.py +++ b/dipy/align/_public.py @@ -212,10 +212,13 @@ def register_dwi_to_template( Returns ------- - warped_b0, mapping: The fist is an array with the b0 volume warped to the - template. If reg_method is "syn", the second is a DiffeomorphicMap class - instance that can be used to transform between the two spaces. Otherwise, - if reg_method is "aff", this is a 4x4 matrix encoding the affine transform. + warped_b0 : ndarray + b0 volume warped to the template. + mapping : DiffeomorphicMap or ndarray + If reg_method is "syn", a DiffeomorphicMap class instance that can be + used to transform between the two spaces. Otherwise, if reg_method is + "aff", a 4x4 matrix encoding the affine transform. + Notes ----- From 011565c0211b773144a63ff3b8dcdd916d560a04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:07:26 -0400 Subject: [PATCH 03/10] DOC: Make the parameter type dwell on a single line Make the parameter type dwell on a single line and move the shape to the description line. Fixes: ``` /dipy/align/imaffine.py:docstring of dipy.align.imaffine.AffineMap.get_affine:3: WARNING: Block quote ends without a blank line; unexpected unindent. ``` raised for example at: https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:794 --- dipy/align/imaffine.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/dipy/align/imaffine.py b/dipy/align/imaffine.py index 5809fa9276..1f3b74e280 100644 --- a/dipy/align/imaffine.py +++ b/dipy/align/imaffine.py @@ -429,9 +429,9 @@ def transform( Returns ------- - transformed : array, shape `sampling_grid_shape` or - `self.codomain_shape` - the transformed image, sampled at the requested grid + transformed : array + the transformed image, sampled at the requested grid, with shape + `sampling_grid_shape` or `self.codomain_shape`. """ transformed = self._apply_transform( @@ -490,9 +490,9 @@ def transform_inverse( Returns ------- - transformed : array, shape `sampling_grid_shape` or - `self.codomain_shape` - the transformed image, sampled at the requested grid + transformed : array + the transformed image, sampled at the requested grid, with shape + `sampling_grid_shape` or `self.codomain_shape`. """ transformed = self._apply_transform( From cb3f5c9cf19fd9303488f159908d1f9df96c4e82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:10:31 -0400 Subject: [PATCH 04/10] DOC: Indent appropriately a parameter docstring Indent appropriately a parameter docstring so that the documentation of the method is displayed correctly. --- dipy/reconst/fwdti.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dipy/reconst/fwdti.py b/dipy/reconst/fwdti.py index 657a6737d8..81475c00b0 100644 --- a/dipy/reconst/fwdti.py +++ b/dipy/reconst/fwdti.py @@ -255,7 +255,7 @@ def wls_iter( Value of the free water isotropic diffusion. Default is set to 3e-3 $mm^{2}.s^{-1}$. Please adjust this value if you are assuming different units of diffusion. - mdreg : float, optimal + mdreg : float, optimal DTI's mean diffusivity regularization threshold. If standard DTI diffusion tensor's mean diffusivity is almost near the free water diffusion value, the diffusion signal is assumed to be only free water From 357193e0062e83536c79181979674b5fbd8bef22 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:12:43 -0400 Subject: [PATCH 05/10] DOC: Enclose inline literal in double backticks Enclose inline literal in double backticks: add missing ending double backticks. Take advantage of the commit to remove its default value: reduces the maintenance burden and avoids the risk of inconsistencies if the default value is changed in the method signature but not the parameter docstring. Fixes: ``` /dipy/segment/bundles.py:docstring of dipy.segment.bundles.RecoBundles.evaluate_results:27: WARNING: Inline literal start-string without end-string. ``` raised for example in: https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:1063 --- dipy/segment/bundles.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dipy/segment/bundles.py b/dipy/segment/bundles.py index 79d0077189..aef2364207 100644 --- a/dipy/segment/bundles.py +++ b/dipy/segment/bundles.py @@ -407,8 +407,8 @@ def recognize( b) "similarity" ``x0 = np.array([0, 0, 0, 0, 0, 0, 1.])`` c) "affine" - ``x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0]) - (default None) + ``x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])`` + slr_bounds : array, optional (default None) slr_select : tuple, optional From afe8ae01fd595e67746827d06041376ea794e2b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:17:09 -0400 Subject: [PATCH 06/10] DOC: Add description to parameter docstring Add description to parameter docstring, and remove its default value: reduces the maintenance burden and avoids the risk of inconsistencies if the default value is changed in the method signature but not the parameter docstring. --- dipy/segment/bundles.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dipy/segment/bundles.py b/dipy/segment/bundles.py index aef2364207..2786c15c21 100644 --- a/dipy/segment/bundles.py +++ b/dipy/segment/bundles.py @@ -410,7 +410,7 @@ def recognize( ``x0 = np.array([0, 0, 0, 0, 0, 0, 1., 1., 1, 0, 0, 0])`` slr_bounds : array, optional - (default None) + SLR bounds. slr_select : tuple, optional Select the number of streamlines from model to neighborhood of model to perform the local SLR. From d8427786b84eb5845961d87ecf5072b9b03b102f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:21:28 -0400 Subject: [PATCH 07/10] DOC: Use the appropriate indentation in docstrings Use the appropriate indentation in docstrings. For multi-line item lists, make all lines have the same indentation. Fixes: ``` /dipy/align/streamlinear.py:docstring of dipy.align.streamlinear.StreamlineLinearRegistration.__init__:53: ERROR: Unexpected indentation. /dipy/align/streamlinear.py:docstring of dipy.align.streamlinear.StreamlineLinearRegistration.__init__:49: WARNING: Block quote ends without a blank line; unexpected unindent. ``` and ``` /dipy/reconst/cti.py:docstring of dipy.reconst.cti.split_cti_params:11: WARNING: Enumerated list ends without a blank line; unexpected unindent. ``` and similar errors raised for example at: https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:802 and https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:884 --- dipy/align/streamlinear.py | 4 ++-- dipy/reconst/cti.py | 2 +- dipy/reconst/dki.py | 2 +- dipy/segment/bundles.py | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/dipy/align/streamlinear.py b/dipy/align/streamlinear.py index d91dac4e2e..37f0897b58 100644 --- a/dipy/align/streamlinear.py +++ b/dipy/align/streamlinear.py @@ -329,10 +329,10 @@ def __init__( If 1D array with: a) 6 elements then only rigid registration is performed with - the 3 first elements for translation and 3 for rotation. + the 3 first elements for translation and 3 for rotation. b) 7 elements also isotropic scaling is performed (similarity). c) 12 elements then translation, rotation (in degrees), - scaling and shearing is performed (affine). + scaling and shearing is performed (affine). Here is an example of x0 with 12 elements: ``x0=np.array([0, 10, 0, 40, 0, 0, 2., 1.5, 1, 0.1, -0.5, 0])`` diff --git a/dipy/reconst/cti.py b/dipy/reconst/cti.py index 9791b19308..04213a2bb0 100644 --- a/dipy/reconst/cti.py +++ b/dipy/reconst/cti.py @@ -111,7 +111,7 @@ def split_cti_params(cti_params): 1. Three diffusion tensor's eigenvalues 2. Three lines of the eigenvector matrix each containing the - first, second and third coordinates of the eigenvector + first, second and third coordinates of the eigenvector 3. Fifteen elements of the kurtosis tensor 4. Twenty-One elements of the covariance tensor diff --git a/dipy/reconst/dki.py b/dipy/reconst/dki.py index 18f2a23288..12f2bab7be 100644 --- a/dipy/reconst/dki.py +++ b/dipy/reconst/dki.py @@ -1958,7 +1958,7 @@ def predict(self, dki_params, S0=1.0): 1. Three diffusion tensor's eigenvalues 2. Three lines of the eigenvector matrix each containing the - first, second and third coordinates of the eigenvector + first, second and third coordinates of the eigenvector 3. Fifteen elements of the kurtosis tensor S0 : float or ndarray (optional) diff --git a/dipy/segment/bundles.py b/dipy/segment/bundles.py index 2786c15c21..1dff8bca03 100644 --- a/dipy/segment/bundles.py +++ b/dipy/segment/bundles.py @@ -530,10 +530,10 @@ def refine( If 1D array with: a) 6 elements then only rigid registration is performed with - the 3 first elements for translation and 3 for rotation. + the 3 first elements for translation and 3 for rotation. b) 7 elements also isotropic scaling is performed (similarity). c) 12 elements then translation, rotation (in degrees), - scaling and shearing are performed (affine). + scaling and shearing are performed (affine). Here is an example of x0 with 12 elements: ``x0=np.array([0, 10, 0, 40, 0, 0, 2., 1.5, 1, 0.1, -0.5, 0])`` From abb974254b3299da29f211d1c90b5c1d55362532 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:34:05 -0400 Subject: [PATCH 08/10] DOC: Add parameter name/type line to return docstring Add parameter name/type line to return docstring. Fixes: ``` /dipy/reconst/fwdti.py:docstring of dipy.reconst.fwdti.wls_iter:17: WARNING: Block quote ends without a blank line; unexpected unindent. ``` raised for example at: https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:961 --- dipy/reconst/fwdti.py | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/dipy/reconst/fwdti.py b/dipy/reconst/fwdti.py index 81475c00b0..3e60d86764 100644 --- a/dipy/reconst/fwdti.py +++ b/dipy/reconst/fwdti.py @@ -271,12 +271,15 @@ def wls_iter( Returns ------- - All parameters estimated from the free water tensor model. - Parameters are ordered as follows: - 1) Three diffusion tensor's eigenvalues - 2) Three lines of the eigenvector matrix each containing the - first, second and third coordinates of the eigenvector - 3) The volume fraction of the free water compartment + fw_params : ndarray + All parameters estimated from the free water tensor model. Parameters + are ordered as follows: + + 1) Three diffusion tensor's eigenvalues + 2) Three lines of the eigenvector matrix each containing the + first, second and third coordinates of the eigenvector + 3) The volume fraction of the free water compartment + """ W = design_matrix From 831c9ac99a345b713d8ac481961937251c822240 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:37:58 -0400 Subject: [PATCH 09/10] DOC: Add an empty line before list items Add an empty line before list items. Fixes: ``` /dipy/reconst/fwdti.py:docstring of dipy.reconst.fwdti.wls_fit_tensor:46: ERROR: Unexpected indentation. ``` and similar errors raised for example at: https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:962 --- dipy/reconst/fwdti.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/dipy/reconst/fwdti.py b/dipy/reconst/fwdti.py index 3e60d86764..0f24950c23 100644 --- a/dipy/reconst/fwdti.py +++ b/dipy/reconst/fwdti.py @@ -385,6 +385,7 @@ def wls_fit_tensor( fw_params : ndarray (x, y, z, 13) Matrix containing in the last dimension the free water model parameters in the following order: + 1) Three diffusion tensor's eigenvalues 2) Three lines of the eigenvector matrix each containing the first, second and third coordinates of the eigenvector @@ -785,6 +786,7 @@ def nls_fit_tensor( fw_params : ndarray (x, y, z, 13) Matrix containing in the dimension the free water model parameters in the following order: + 1) Three diffusion tensor's eigenvalues 2) Three lines of the eigenvector matrix each containing the first, second and third coordinates of the eigenvector From 76193e1f42ad5e9b541436a9bb6861fda4b66249 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Tue, 20 Aug 2024 19:44:28 -0400 Subject: [PATCH 10/10] DOC: Indent appropriately enumerated lists Indent appropriately enumerated lists, and add an empty line before the list. Take advantage of the commit to - Format properly the list making each item start with a dash. - Dedent a list to avoid excessive indentation and potential horizontal scroll. Fixes: ``` /dipy/reconst/dki.py:docstring of dipy.reconst.dki.DiffusionKurtosisModel:7: WARNING: Enumerated list ends without a blank line; unexpected unindent. ``` and ``` /dipy/reconst/qti.py:docstring of dipy.reconst.qti.QtiModel.__init__:14: WARNING: Block quote ends without a blank line; unexpected unindent. ``` raised for example at https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:885 and https://github.com/dipy/dipy/actions/runs/10472634043/job/29002561651#step:5:979 --- dipy/reconst/dki.py | 12 ++++++------ dipy/reconst/qti.py | 13 ++++++------- 2 files changed, 12 insertions(+), 13 deletions(-) diff --git a/dipy/reconst/dki.py b/dipy/reconst/dki.py index 12f2bab7be..4e968dc66b 100644 --- a/dipy/reconst/dki.py +++ b/dipy/reconst/dki.py @@ -1756,12 +1756,12 @@ def __init__(self, gtab, fit_method="WLS", return_S0_hat=False, *args, **kwargs) fit_method : str or callable, optional str be one of the following: - - 'OLS' or 'ULLS' for ordinary least squares. - - 'WLS', 'WLLS' or 'UWLLS' for weighted ordinary least squares. - See func:`dki.ls_fit_dki`. - - 'CLS' for LMI constrained ordinary least squares [3]_. - - 'CWLS' for LMI constrained weighted least squares [3]_. - See func:`dki.cls_fit_dki`. + - 'OLS' or 'ULLS' for ordinary least squares. + - 'WLS', 'WLLS' or 'UWLLS' for weighted ordinary least squares. + See func:`dki.ls_fit_dki`. + - 'CLS' for LMI constrained ordinary least squares [3]_. + - 'CWLS' for LMI constrained weighted least squares + [3]_. See func:`dki.cls_fit_dki`. callable has to have the signature: ``fit_method(design_matrix, data, *args, **kwargs)`` diff --git a/dipy/reconst/qti.py b/dipy/reconst/qti.py index 9dffad4030..4b38e16904 100644 --- a/dipy/reconst/qti.py +++ b/dipy/reconst/qti.py @@ -722,13 +722,12 @@ def __init__(self, gtab, fit_method="WLS", cvxpy_solver="SCS"): Gradient table with b-tensors. fit_method : str, optional Must be one of the following: - 'OLS' for ordinary least squares - :func:`qti._ols_fit` - 'WLS' for weighted least squares - :func:`qti._wls_fit` - 'SDPDc' for semidefinite programming with positivity - constraints applied [2]_ - :func:`qti._sdpdc_fit` + + - 'OLS' for ordinary least squares :func:`qti._ols_fit` + - 'WLS' for weighted least squares :func:`qti._wls_fit` + - 'SDPDc' for semidefinite programming with positivity constraints + applied [2]_ :func:`qti._sdpdc_fit` + cvxpy_solver: str, optionals solver for the SDP formulation. default: 'SCS'