From a1298f6ba4376a0541c90d4d35132d1f0d56b9dc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Wed, 23 Oct 2024 20:23:52 -0400 Subject: [PATCH 1/4] DOC: Miscellaneous docstring improvements Miscellaneous docstring improvements: - Add missing parameter docstrings. - Fix parameter names. - Document optional parameters as such. - Remove the parameter default values from the docstrings: the method signature shows already the default values in the documentation and reduces the maintenance burden. - Use double backticks for inline code literals. - Add a whitespace between the parameter name and the colon to increase consistency across the docstrings. --- src/eddymotion/model/_dipy.py | 31 +++++++++++++++++++-------- src/eddymotion/model/_sklearn.py | 27 +++++++++++------------ src/eddymotion/registration/ants.py | 12 +++++------ src/eddymotion/testing/simulations.py | 8 +++---- 4 files changed, 45 insertions(+), 33 deletions(-) diff --git a/src/eddymotion/model/_dipy.py b/src/eddymotion/model/_dipy.py index e64b9e27..de13bcbd 100644 --- a/src/eddymotion/model/_dipy.py +++ b/src/eddymotion/model/_dipy.py @@ -53,12 +53,14 @@ def gp_prediction( Parameters ---------- - model: :obj:`~sklearn.gaussian_process.GaussianProcessRegressor` + model : :obj:`~sklearn.gaussian_process.GaussianProcessRegressor` A fitted GaussianProcessRegressor model. gtab : :obj:`~dipy.core.gradients.GradientTable` or :obj:`~np.ndarray` Gradient table with one or more orientations at which the GP will be evaluated. - mask: :obj:`numpy.ndarray` + mask: :obj:`numpy.ndarray`, optional A boolean mask indicating which voxels to use (optional). + return_std : bool, optional + Whether to return the standard deviation of the predicted signal. Returns ------- @@ -100,8 +102,16 @@ def __init__( Parameters ---------- - kernel : :obj:`~sklearn.gaussian_process.kernels.Kernel` + kernel_model : :obj:`~sklearn.gaussian_process.kernels.Kernel`, optional Kernel model to calculate the GP's covariance matrix. + lambda_s : :obj:`float`, optional + Signal scale parameter determining the variability of the signal. + a : :obj:`float`, optional + Distance scale parameter determining how fast the covariance + decreases as one moves along the surface of the sphere. Must have a + positive value. + sigma_sq : :obj:`float`, optional + Uncertainty of the measured values. References ---------- @@ -136,11 +146,14 @@ def fit( ---------- gtab : :obj:`~dipy.core.gradients.GradientTable` or :obj:`~np.ndarray` The gradient table corresponding to the training data. - y : :obj:`~numpy.ndarray` + data : :obj:`~numpy.ndarray` The measured signal from one voxel. mask : :obj:`~numpy.ndarray` A boolean array used to mark the coordinates in the data that should be analyzed that has the shape data.shape[:-1] + random_state: :obj:`int`, optional + Determines random number generation used to initialize the centers + of the kernel bounds. Returns ------- @@ -208,9 +221,9 @@ class GPFit: Attributes ---------- - model: :obj:`~sklearn.gaussian_process.GaussianProcessRegressor` + model : :obj:`~sklearn.gaussian_process.GaussianProcessRegressor` The fitted Gaussian process regressor object. - mask: :obj:`~numpy.ndarray` + mask : :obj:`~numpy.ndarray` The boolean mask used during fitting (can be ``None``). """ @@ -225,10 +238,10 @@ def __init__( Parameters ---------- - model: :obj:`~sklearn.gaussian_process.GaussianProcessRegressor` + model : :obj:`~sklearn.gaussian_process.GaussianProcessRegressor` The fitted Gaussian process regressor object. - mask: :obj:`~numpy.ndarray` - The boolean mask used during fitting (can be ``None``). + mask : :obj:`~numpy.ndarray`, optional + The boolean mask used during fitting. """ self.model = model diff --git a/src/eddymotion/model/_sklearn.py b/src/eddymotion/model/_sklearn.py index 8e69cc6d..cf215455 100644 --- a/src/eddymotion/model/_sklearn.py +++ b/src/eddymotion/model/_sklearn.py @@ -199,9 +199,9 @@ def __call__( Parameters ---------- - X: :obj:`~numpy.ndarray` + X : :obj:`~numpy.ndarray` Gradient table (X) - Y: :obj:`~numpy.ndarray`, optional + Y : :obj:`~numpy.ndarray`, optional Gradient table (Y, optional) eval_gradient : :obj:`bool`, optional Determines whether the gradient with respect to the log of @@ -275,13 +275,13 @@ def __init__( Parameters ---------- - a : :obj:`float` + a : :obj:`float`, optional Minimum angle in rads. - lambda_s : :obj:`float` + lambda_s : :obj:`float`, optional The :math:`\lambda_s` hyperparameter. - a_bounds : :obj:`tuple` - Bounds for the a parameter. - lambda_s_bounds : :obj:`tuple` + a_bounds : :obj:`tuple`, optional + Bounds for the ``a`` parameter. + lambda_s_bounds : :obj:`tuple`, optional Bounds for the :math:`\lambda_s` hyperparameter. """ @@ -306,9 +306,9 @@ def __call__( Parameters ---------- - X: :obj:`~numpy.ndarray` + X : :obj:`~numpy.ndarray` Gradient table (X) - Y: :obj:`~numpy.ndarray`, optional + Y : :obj:`~numpy.ndarray`, optional Gradient table (Y, optional) eval_gradient : :obj:`bool`, optional Determines whether the gradient with respect to the log of @@ -323,7 +323,7 @@ def __call__( K_gradient : ndarray of shape (n_samples_X, n_samples_X, n_dims),\ optional The gradient of the kernel k(X, X) with respect to the log of the - hyperparameter of the kernel. Only returned when `eval_gradient` + hyperparameter of the kernel. Only returned when ``eval_gradient`` is True. """ @@ -394,14 +394,13 @@ def compute_pairwise_angles( ---------- X : {array-like, sparse matrix} of shape (n_samples_X, n_features) Input data. - Y : {array-like, sparse matrix} of shape (n_samples_Y, n_features), \ - default=None + Y : {array-like, sparse matrix} of shape (n_samples_Y, n_features), optional Input data. If ``None``, the output will be the pairwise similarities between all samples in ``X``. - dense_output : :obj:`bool`, default=True + dense_output : :obj:`bool`, optional Whether to return dense output even when the input is sparse. If ``False``, the output is sparse if both input arrays are sparse. - closest_polarity : :obj:`bool`, default=True + closest_polarity : :obj:`bool`, optional ``True`` to consider the smallest of the two angles between the crossing lines resulting from reversing each vector pair. diff --git a/src/eddymotion/registration/ants.py b/src/eddymotion/registration/ants.py index 149108f8..2f1c9495 100644 --- a/src/eddymotion/registration/ants.py +++ b/src/eddymotion/registration/ants.py @@ -73,7 +73,7 @@ def _to_nifti( filename : :obj:`os.pathlike` The file path where the NIfTI file will be saved. clip : :obj:`bool`, optional - Whether to apply clipping to the data before saving, by default True. + Whether to apply clipping to the data before saving. """ data = np.squeeze(data) @@ -144,7 +144,7 @@ def _get_ants_settings(settings: str = "b0-to-b0_level0") -> Path: Parameters ---------- settings : :obj:`str`, optional - Name of the settings configuration, by default ``"b0-to-b0_level0"``. + Name of the settings configuration. Returns ------- @@ -225,13 +225,13 @@ def generate_command( moving_path : :obj:`os.pathlike` Path to the moving image. fixedmask_path : :obj:`os.pathlike` or :obj:`list`, optional - Path to the fixed image mask, by default None. + Path to the fixed image mask. movingmask_path : :obj:`os.pathlike` or :obj:`list`, optional - Path to the moving image mask, by default None. + Path to the moving image mask. init_affine : :obj:`os.pathlike`, optional - Initial affine transformation, by default None. + Initial affine transformation. default : :obj:`str`, optional - Default settings configuration, by default "b0-to-b0_level0". + Default settings configuration. **kwargs : :obj:`dict` Additional parameters for ANTs registration. diff --git a/src/eddymotion/testing/simulations.py b/src/eddymotion/testing/simulations.py index 2c1aa11e..b849d3bb 100644 --- a/src/eddymotion/testing/simulations.py +++ b/src/eddymotion/testing/simulations.py @@ -89,7 +89,7 @@ def create_random_polar_coordinates( hsph_dirs : :obj:`int` Number of hemisphere directions. seed : :obj:`int`, optional - Seed for the random number generator, by default 1234. + Seed for the random number generator. Returns ------- @@ -114,9 +114,9 @@ def create_diffusion_encoding_gradient_dirs( hsph_dirs : :obj:`int` Number of hemisphere directions. iterations : :obj:`int`, optional - Number of iterations for charge dispersion, by default 5000. + Number of iterations for charge dispersion. seed : :obj:`int`, optional - Seed for the random number generator, by default 1234. + Seed for the random number generator. Returns ------- @@ -148,7 +148,7 @@ def create_single_shell_gradient_table( bval_shell : :obj:`float` Shell b-value. iterations : :obj:`int`, optional - Number of iterations for charge dispersion, by default 5000. + Number of iterations for charge dispersion. Returns ------- From ba570eef42c3db888e71511d89247d26b469bee6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Wed, 23 Oct 2024 20:37:24 -0400 Subject: [PATCH 2/4] DOC: Miscellaneous improvements to comments Miscellaneous improvements to comments: - Use `scikit-learn` as in other appearances. - Improve wording. --- src/eddymotion/model/_dipy.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/src/eddymotion/model/_dipy.py b/src/eddymotion/model/_dipy.py index de13bcbd..9c7b24e0 100644 --- a/src/eddymotion/model/_dipy.py +++ b/src/eddymotion/model/_dipy.py @@ -162,12 +162,14 @@ def fit( """ - # Extract b-vecs: Scikit learn wants (n_samples, n_features) - # where n_features is 3, and n_samples the different diffusion orientations. + # Extract b-vecs: scikit-learn wants (n_samples, n_features) + # where n_features is 3, and n_samples the different diffusion-encoding + # gradient orientations. X = gtab.bvecs if hasattr(gtab, "bvecs") else np.asarray(gtab) - # Data must be shapes (n_samples, n_targets) where n_samples is - # the number of diffusion orientations, and n_targets is number of voxels. + # Data must have shape (n_samples, n_targets) where n_samples is + # the number of diffusion-encoding gradient orientations, and n_targets + # is number of voxels. y = ( data[mask[..., None]] if mask is not None else np.reshape(data, (-1, data.shape[-1])) ).T From c8c112dd2f91c92124e61cdca118b3fc884cd4ca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jon=20Haitz=20Legarreta=20Gorro=C3=B1o?= Date: Wed, 23 Oct 2024 20:33:24 -0400 Subject: [PATCH 3/4] STYLE: Increase consistency in function parameter order Increase consistency in the `gp_prediction` function parameter order: make the data (gtab and optional mask) dwell next to each other. --- src/eddymotion/model/_dipy.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/eddymotion/model/_dipy.py b/src/eddymotion/model/_dipy.py index 9c7b24e0..6a657a15 100644 --- a/src/eddymotion/model/_dipy.py +++ b/src/eddymotion/model/_dipy.py @@ -39,8 +39,8 @@ def gp_prediction( - gtab: GradientTable | np.ndarray, model: GaussianProcessRegressor, + gtab: GradientTable | np.ndarray, mask: np.ndarray | None = None, return_std: bool = False, ) -> np.ndarray: @@ -267,7 +267,7 @@ def predict( A 3D or 4D array with the simulated gradient(s). """ - return gp_prediction(gtab, self.model, mask=self.mask) + return gp_prediction(self.model, gtab, mask=self.mask) def _rasb2dipy(gradient): From 79abd041fdd3271130dbfd619fa5ac59a9b2d1d6 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Sat, 26 Oct 2024 07:52:49 +0200 Subject: [PATCH 4/4] Update src/eddymotion/model/_dipy.py --- src/eddymotion/model/_dipy.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/eddymotion/model/_dipy.py b/src/eddymotion/model/_dipy.py index 6a657a15..96133c8e 100644 --- a/src/eddymotion/model/_dipy.py +++ b/src/eddymotion/model/_dipy.py @@ -57,7 +57,7 @@ def gp_prediction( A fitted GaussianProcessRegressor model. gtab : :obj:`~dipy.core.gradients.GradientTable` or :obj:`~np.ndarray` Gradient table with one or more orientations at which the GP will be evaluated. - mask: :obj:`numpy.ndarray`, optional + mask : :obj:`numpy.ndarray`, optional A boolean mask indicating which voxels to use (optional). return_std : bool, optional Whether to return the standard deviation of the predicted signal.