Fixed typos, fixed one incomplete doc strings, etc. (#765)

* Fixed typos, fixed one incomplete doc string (see formula.py l19; is this correct?), made docstring punctation and emphasis (more) consistent. * Fixed too long lines in my earlier commit. * Remove double backticks in docstrings * Update documentation dependencies --------- Co-authored-by: Tomas Capretto <[email protected]>
bambinos · Nov 10, 2024 · 3a30784 · 3a30784
1 parent 7a18fb9
commit 3a30784
Show file tree

Hide file tree

Showing 29 changed files with 247 additions and 218 deletions.
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -32,9 +32,9 @@ jobs:
           python -m pip install quartodoc==0.6.1
 
       - name: Set up Quarto
-        uses: quarto-dev/quarto-actions/setup@v2   
+        uses: quarto-dev/quarto-actions/setup@v2
         with:
-          version: 1.2.280 # since this is my local version, we could change it
+          version: 1.5.57 # since this is my local version, we could change it
 
       - name: Build docs
         shell: bash
@@ -43,7 +43,7 @@ jobs:
           quarto render docs
           touch docs/_site/.nojekyll
 
-      - name: Publish to GitHub 
+      - name: Publish to GitHub
         if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags') # Only from main or a tag
         uses: quarto-dev/quarto-actions/publish@v2
         with:

diff --git a/bambi/backend/links.py b/bambi/backend/links.py
@@ -3,7 +3,7 @@
 
 
 def probit(x):
-    """Probit function that ensures result is in (0, 1)"""
+    """Probit function that ensures result is in (0, 1)."""
     eps = np.finfo(float).eps
     result = 0.5 + 0.5 * pt.erf(x / pt.sqrt(2))
     result = pt.switch(pt.eq(result, 0), eps, result)
@@ -13,7 +13,7 @@ def probit(x):
 
 
 def cloglog(x):
-    """Cloglog function that ensures result is in (0, 1)"""
+    """Cloglog function that ensures result is in (0, 1)."""
     eps = np.finfo(float).eps
     result = 1 - pt.exp(-pt.exp(x))
     result = pt.switch(pt.eq(result, 0), eps, result)
@@ -23,7 +23,7 @@ def cloglog(x):
 
 
 def logit(x):
-    """Logit function that ensures result is in (0, 1)"""
+    """Logit function that ensures result is in (0, 1)."""
     eps = np.finfo(float).eps
     result = pt.sigmoid(x)
     result = pt.switch(pt.eq(result, 0), eps, result)

diff --git a/bambi/backend/model_components.py b/bambi/backend/model_components.py
@@ -61,7 +61,7 @@ def build_intercept(self, bmb_model):
             self.output += InterceptTerm(self.component.intercept_term).build(bmb_model)
 
     def build_offsets(self):
-        """Add intercept term to the PyMC model.
+        """Add intercept term to the PyMC model
 
         We have linear predictors of the form 'X @ b + Z @ u'. This is technically part of
         'X @ b' but it is added separately for convenience reasons.
@@ -70,7 +70,7 @@ def build_offsets(self):
             self.output += offset.data.squeeze()
 
     def build_common_terms(self, pymc_backend, bmb_model):
-        """Add common (fixed) terms to the PyMC model.
+        """Add common (fixed) terms to the PyMC model
 
         We have linear predictors of the form 'X @ b + Z @ u'.
         This creates the 'b' parameter vector in PyMC, computes `X @ b`, and adds it to `self.mu`.
@@ -123,7 +123,7 @@ def build_hsgp_terms(self, pymc_backend):
             self.output += hsgp_term.build()
 
     def build_group_specific_terms(self, pymc_backend, bmb_model):
-        """Add group-specific (random or varying) terms to the PyMC model.
+        """Add group-specific (random or varying) terms to the PyMC model
 
         We have linear predictors of the form 'X @ b + Z @ u'.
         This creates the 'u' parameter vector in PyMC, computes `Z @ u`, and adds it to

diff --git a/bambi/backend/pymc.py b/bambi/backend/pymc.py
@@ -59,7 +59,7 @@ def __init__(self):
         self.pymc_methods = inference_methods.names["pymc"]
 
     def build(self, spec):
-        """Compile the PyMC model from an abstract model specification.
+        """Compile the PyMC model from an abstract model specification
 
         Parameters
         ----------
@@ -153,7 +153,7 @@ def run(
         return result
 
     def build_potentials(self, spec):
-        """Add potentials to the PyMC model.
+        """Add potentials to the PyMC model
 
         Potentials are arbitrary quantities that are added to the model log likelihood.
         See 'Factor Potentials' in
@@ -422,7 +422,7 @@ def distributional_components(self):
 
 
 def _posterior_samples_to_idata(samples, model):
-    """Create InferenceData from samples.
+    """Create InferenceData from samples
 
     Parameters
     ----------

diff --git a/bambi/backend/terms.py b/bambi/backend/terms.py
@@ -167,7 +167,7 @@ def name(self):
 
 
 class InterceptTerm:
-    """Representation of an intercept term in a PyMC model.
+    """Representation of an intercept term in a PyMC model
 
     Parameters
     ----------
@@ -199,7 +199,7 @@ def name(self):
 
 
 class ResponseTerm:
-    """Representation of a response term in a PyMC model.
+    """Representation of a response term in a PyMC model
 
     Parameters
     ----------
@@ -214,19 +214,19 @@ def __init__(self, term, family):
         self.family = family
 
     def build(self, pymc_backend, bmb_model):
-        """Create and return the response distribution for the PyMC model.
+        """Create and return the response distribution for the PyMC model
 
         Parameters
         ----------
         pymc_backend : bambi.backend.PyMCModel
             The object with all the backend information
         bmb_model : bambi.Model
-            The Bambi model instance
+            The Bambi model instance.
 
         Returns
         -------
         dist : pm.Distribution
-            The response distribution
+            The response distribution.
         """
         data = np.squeeze(self.term.data)
         parent_name = self.family.likelihood.parent
@@ -541,7 +541,7 @@ def get_covariance_functions(self):
         Returns
         -------
         Sequence[pm.gp.Covariance]
-            A covariance function that can be used with a GP in PyMC
+            A covariance function that can be used with a GP in PyMC.
         """
 
         # Get the callable that creates the function

diff --git a/bambi/backend/utils.py b/bambi/backend/utils.py
@@ -86,7 +86,7 @@ def get_linkinv(link, invlinks):
     Returns
     -------
         callable
-        The link function
+        The link function.
     """
     # If the name is in the backend, get it from there
     if link.name in invlinks:
@@ -126,7 +126,7 @@ def make_weighted_logp(dist: pm.Distribution):
 
     Returns
     -------
-    A function that computes the weighted logp
+    A function that computes the weighted logp.
     """
 
     def logp(value, *dist_params, weights):
@@ -137,7 +137,7 @@ def logp(value, *dist_params, weights):
 
 
 def get_dist_args(dist: pm.Distribution) -> list[str]:
-    """Get the argument names of a PyMC distribution.
+    """Get the argument names of a PyMC distribution
 
     The argument names are the names of the parameters of the distribution.
 

diff --git a/bambi/data/datasets.py b/bambi/data/datasets.py
@@ -182,7 +182,7 @@
 * sex: Sex of the patient
 * disease: The type of disease. Can be "AN", "GN", "PKG", or "other"
 
-McGilchrist, C. A., & Aisbett, C. W. (1991). Regression with frailty in survival analysis. 
+McGilchrist, C. A., & Aisbett, C. W. (1991). Regression with frailty in survival analysis.
 Biometrics, 47(2), 461-466
 """,
     ),
@@ -195,8 +195,8 @@ def get_data_home(data_home=None):
     This folder is used to avoid downloading the data several times.
 
     By default the data dir is set to a folder named 'bambi_data' in the user home folder.
-    Alternatively, it can be set by the ``"BAMBI_DATA"`` environment variable or programmatically by
-    giving an explicit folder path. The ``"~"`` symbol is expanded to the user home folder. If the
+    Alternatively, it can be set by the `"BAMBI_DATA"` environment variable or programmatically by
+    giving an explicit folder path. The `"~"` symbol is expanded to the user home folder. If the
     folder does not already exist, it is automatically created.
 
     Parameters
@@ -218,7 +218,7 @@ def clear_data_home(data_home=None):
     Parameters
     ----------
     data_home: str
-        The path to Bambi data dir. By default a folder named ``"bambi_data"`` in the user home
+        The path to Bambi data dir. By default a folder named `"bambi_data"` in the user home
         folder.
     """
     data_home = get_data_home(data_home)
@@ -244,9 +244,9 @@ def load_data(dataset=None, data_home=None):
 
     Run with no parameters to get a list of all available data sets.
 
-    The directory to save can also be set with the environment variable ``BAMBI_HOME``.
+    The directory to save can also be set with the environment variable `BAMBI_HOME`.
     The checksum of the dataset is checked against a hardcoded value to watch for data corruption.
-    Run ``bmb.clear_data_home()`` to clear the data directory.
+    Run `bmb.clear_data_home()` to clear the data directory.
 
     Parameters
     ----------

diff --git a/bambi/defaults/families.py b/bambi/defaults/families.py
@@ -299,14 +299,14 @@
 
 
 def get_builtin_family(name):
-    """Generate a built-in ``bambi.families.Family`` instance.
+    """Generate a built-in `bambi.families.Family` instance.
 
-    Given the name of a built-in family, this function returns a ``bambi.families.Family`` instance
+    Given the name of a built-in family, this function returns a `bambi.families.Family` instance
     that is constructed by calling other utility functions that construct the
-    ``bambi.families.Likelihood`` and the ``bambi.priors.Prior`` instances that are needed to build
+    `bambi.families.Likelihood` and the `bambi.priors.Prior` instances that are needed to build
     the family.
 
-    The available built-in families are found in ``SETTINGS_FAMILIES``.
+    The available built-in families are found in `SETTINGS_FAMILIES`.
 
     Parameters
     ----------
@@ -316,7 +316,7 @@ def get_builtin_family(name):
     Raises
     ------
     ValueError
-        If ``name`` is not the name of a built-in family.
+        If `name` is not the name of a built-in family.
 
     Returns
     -------

diff --git a/bambi/defaults/utils.py b/bambi/defaults/utils.py
@@ -8,20 +8,20 @@
 def generate_prior(dist, **kwargs):
     """Generate a Prior distribution.
 
-    The parameter ``kwargs`` is used to pass hyperpriors that are assigned to the parameters of
+    The parameter `kwargs` is used to pass hyperpriors that are assigned to the parameters of
     the prior to be built.
 
     Parameters
     ----------
     dist: str, int, float
         If a string, it is the name of the prior distribution with default values taken from
-        ``SETTINGS_DISTRIBUTIONS``. If a number, it is a factor used to scale the standard deviation
+        `SETTINGS_DISTRIBUTIONS`. If a number, it is a factor used to scale the standard deviation
         of the priors generated automatically by Bambi.
 
     Raises
     ------
     ValueError
-        If ``dist`` is not a string or a number.
+        If `dist` is not a string or a number.
 
     Returns
     -------
@@ -84,12 +84,12 @@ def get_default_prior(term_type, **kwargs):
     Raises
     ------
     ValueError
-        If ``term_type`` is not within the values listed above.
+        If `term_type` is not within the values listed above.
 
     Returns
     -------
     prior: Prior
-        The instance of Prior according to the ``term_type``.
+        The instance of Prior according to the `term_type`.
     """
     if term_type in ["intercept", "common"]:
         prior = generate_prior("Normal")
@@ -115,8 +115,8 @@ def generate_likelihood(name, params, parent):
         The name of the likelihood function.
     args: dict
         Indicates the auxiliary parameters and the values for their default priors. The keys are the
-        names of the parameters and the values are passed to ``generate_prior()`` to obtain the
-        actual instance of ``bambi.Prior``.
+        names of the parameters and the values are passed to `generate_prior()` to obtain the
+        actual instance of `bambi.Prior`.
     parent: str
         The name of the parent parameter. In other words, the name of the mean parameter in the
         likelihood function.

diff --git a/bambi/families/family.py b/bambi/families/family.py
@@ -9,7 +9,7 @@
 
 
 class Family:
-    """A specification of model family.
+    """A specification of model family
 
     Parameters
     ----------
@@ -142,7 +142,7 @@ def posterior_predictive(self, model, posterior, **kwargs):
         Returns
         -------
         xr.DataArray
-            A data array with the draws from the posterior predictive distribution
+            A data array with the draws from the posterior predictive distribution.
         """
         response_dist = get_response_dist(model.family)
         response_term = model.response_component.term
@@ -307,12 +307,12 @@ def get_response_dist(family):
     Parameters
     ----------
     family : bambi.Family
-        The family for which the response distribution is wanted
+        The family for which the response distribution is wanted.
 
     Returns
     -------
     pm.Distribution
-        The response distribution
+        The response distribution.
     """
     mapping = {"Cumulative": pm.Categorical, "StoppingRatio": pm.Categorical}
 
@@ -328,25 +328,25 @@ def get_response_dist(family):
 def expand_array(x, ndim):
     """Add dimensions to an array to match the number of desired dimensions
 
-    If x.ndim < ndim, it adds ndim - x.ndim dimensions after the last axis. If not, it is left
-    untouched.
+    If `x.ndim < ndim`, it adds `ndim - x.ndim` dimensions after the last axis. If not,
+    it is left untouched.
 
-    For example, if we have a normal regression model with n = 1000, chains = 2, and draws = 500
-    the shape of the draws of mu will be (2, 500, 1000) but the shape of the draws of sigma will be
-    (2, 500). This function makes sure the shape of the draws of sigma is (2, 500, 1) which is
-    comaptible with (2, 500, 1000).
+    For example, if we have a normal regression model with `n = 1000`, `chains = 2`, and
+    `draws = 500` the shape of the draws of mu will be `(2, 500, 1000)` but the shape of the
+    draws of sigma will be `(2, 500)`. This function makes sure the shape of the draws of
+    sigma is `(2, 500, 1)` which is comaptible with `(2, 500, 1000)`.
 
     Parameters
     ----------
     x : np.ndarray
         The array
     ndim : int
-        The number of desired dimensions
+        The number of desired dimensions.
 
     Returns
     -------
     np.ndarray
-        The array with the expanded dimensions
+        The array with the expanded dimensions.
     """
     if x.ndim == ndim:
         return x

diff --git a/bambi/families/likelihood.py b/bambi/families/likelihood.py
@@ -29,7 +29,7 @@
 
 
 class Likelihood:
-    """Representation of a Likelihood function for a Bambi model.
+    """Representation of a Likelihood function for a Bambi model
 
     Notes:
     * `parent` must be in `params`