Double-check existing docstrings + start preparing release (#935)

* Changes

* Update more docstrings and update PyMC to 5.26

* Final pass at docstrings

* Update index and readme

Author: tomicapretto

README.md

@@ -153,7 +153,7 @@ If you use Bambi and want to cite it please use
 
 Bambi is a community project and welcomes contributions. Additional information can be found in the [Contributing](https://github.com/bambinos/bambi/blob/main/CONTRIBUTING.md) Readme.
 
-For a list of contributors see the [GitHub contributor](https://github.com/bambinos/bambi/graphs/contributors) page
+For a list of contributors see the [GitHub contributor](https://github.com/bambinos/bambi/graphs/contributors) page.
 
 ## Donations
 
@@ -163,6 +163,8 @@ If you want to support Bambi financially, you can [make a donation](https://numf
 
 Bambi wishes to maintain a positive community. Additional details can be found in the [Code of Conduct](https://github.com/bambinos/bambi/blob/main/CODE_OF_CONDUCT.md)
 
+If you have experienced or witnessed any behaviour that violates our Code of Conduct, we encourage you to report it through [this contact form](https://bambinos.github.io/bambi/contact.html).
+
 ## License
 
 [MIT License](https://github.com/bambinos/bambi/blob/main/LICENSE)

bambi/__init__.py

@@ -4,14 +4,13 @@
 
 from pymc import math
 
-from .backend import PyMCModel
-from .config import config
-from .data import clear_data_home, load_data
-from .families import Family, Likelihood, Link
-from .formula import Formula
-from .models import Model
-from .priors import Prior
-from . import interpret
+from bambi.backend import PyMCModel
+from bambi.config import config
+from bambi.data import clear_data_home, load_data
+from bambi.families import Family, Likelihood, Link
+from bambi.formula import Formula
+from bambi.models import Model
+from bambi.priors import Prior
 
 __version__ = version("bambi")
 

bambi/data/__init__.py

@@ -1,5 +1,5 @@
 """Code for loading datasets."""
 
-from .datasets import clear_data_home, load_data
+from bambi.data.datasets import clear_data_home, load_data
 
 __all__ = ["clear_data_home", "load_data"]

bambi/data/datasets.py

@@ -189,7 +189,7 @@
 }
 
 
-def get_data_home(data_home=None):
+def get_data_home(data_home: str | None = None):
     """Return the path of the Bambi data dir.
 
     This folder is used to avoid downloading the data several times.
@@ -201,7 +201,7 @@ def get_data_home(data_home=None):
 
     Parameters
     ----------
-    data_home: str
+    data_home :  str or None, optional
         The path to Bambi data dir.
     """
     if data_home is None:
@@ -218,8 +218,8 @@ def clear_data_home(data_home: str | None = None):
     Parameters
     ----------
     data_home: str or None, optional
-        The path to Bambi data dir. By default a folder named `"bambi_data"` in the user home
-        folder.
+        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)
     shutil.rmtree(data_home)
@@ -250,14 +250,14 @@ def load_data(dataset: str | None = None, data_home: str | None = None):
 
     Parameters
     ----------
-    dataset: str
+    dataset : str or None, optional
         Name of dataset to load.
-    data_home: str, optional
-        Where to save remote datasets
+    data_home : str or None, optional
+        Where to save remote datasets.
 
     Returns
     -------
-    pandas.DataFrame
+    pd.DataFrame or str
     """
     home_dir = get_data_home(data_home=data_home)
 
@@ -274,19 +274,29 @@ def load_data(dataset: str | None = None, data_home: str | None = None):
                     f"({datafile.checksum}), file may be corrupted. Run `bambi.clear_data_home()` "
                     "and try again, or please open an issue."
                 )
+
         return pd.read_csv(file_path)
-    else:
-        if dataset is None:
-            return _list_datasets(home_dir)
-        else:
-            raise ValueError(
-                f"Dataset {dataset} not found! "
-                f"The following are available:\n{_list_datasets(home_dir)}"
-            )
+
+    if dataset is None:
+        return _list_datasets(home_dir)
+
+    raise ValueError(
+        f"Dataset {dataset} not found! " f"The following are available:\n{_list_datasets(home_dir)}"
+    )
 
 
 def _list_datasets(home_dir):
-    """Get a string representation of all available datasets with descriptions."""
+    """Get a string representation of all available datasets with descriptions.
+
+    Parameters
+    ----------
+    home_dir : str
+        Name of the home directoy.
+
+    Returns
+    -------
+    str
+    """
     lines = []
     for filename, resource in itertools.chain(DATASETS.items()):
         file_path = os.path.join(home_dir, filename)

bambi/defaults/hsgp.py

@@ -1,5 +1,4 @@
-"""This module contains the default priors for the parameters of different covariance kernels
-that can be used in HSGP terms."""
+"""Default priors for parameters of covariance kernels in HSGP terms."""
 
 # fmt: off
 HSGP_COV_PARAMS_DEFAULT_PRIORS = {

bambi/defaults/utils.py

@@ -13,7 +13,7 @@ def generate_prior(dist, **kwargs):
 
     Parameters
     ----------
-    dist: str, int, float
+    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
         of the priors generated automatically by Bambi.
@@ -28,14 +28,16 @@ def generate_prior(dist, **kwargs):
     Prior
         The Prior instance.
     """
+
+    if not isinstance(dist, str | int | float):
+        raise ValueError("'dist' must be the name of a distribution or a numeric value.")
+
     if isinstance(dist, str):
         prior = Prior(dist, **SETTINGS_DISTRIBUTIONS[dist])
         if kwargs:
             prior.update(**{k: generate_prior(v) for k, v in kwargs.items()})
-    elif isinstance(dist, (int, float)):
-        prior = dist
     else:
-        raise ValueError("'dist' must be the name of a distribution or a numeric value.")
+        prior = dist
     return prior
 
 
@@ -52,7 +54,7 @@ def generate_prior_hsgp(cov_name: str):
 
     Returns
     -------
-    dict[str, Prior]
+    dict of str to Prior
         The priors for the parameters of the covariance function
     """
     config = HSGP_COV_PARAMS_DEFAULT_PRIORS[cov_name]
@@ -84,7 +86,7 @@ def get_default_prior(term_type, **kwargs):
     Raises
     ------
     ValueError
-        If `term_type` is not within the values listed above.
+        If `term_type` is not one of the values listed above.
 
     Returns
     -------
@@ -111,13 +113,13 @@ def generate_likelihood(name, params, parent):
 
     Parameters
     ----------
-    name: str
+    name : str
         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
+    params : dict
+        Indicates the auxiliary parameters and the values for their default priors.
+        Keys are names of the parameters and values are passed to `generate_prior()` to obtain the
         actual instance of `bambi.Prior`.
-    parent: str
+    parent : str
         The name of the parent parameter. In other words, the name of the mean parameter in the
         likelihood function.
 
@@ -136,13 +138,13 @@ def generate_family(name, likelihood, link, family, default_priors=None):
     ----------
     name : str
         The name of the family.
-    likelihood: bambi.Likelihood
+    likelihood : bambi.Likelihood
         A representation of the likelihood function that corresponds to the family being created.
     link : bambi.Link
         A representation of the link function that corresponds to the family being created.
     family : subclass of bambi.Family
         A subclass of bambi.Family that generates the instance of the desired family.
-    default_priors : dict
+    default_priors : dict or None, optional
         Default priors for non-parent parameters.
 
     Returns

bambi/families/family.py

@@ -1,5 +1,3 @@
-from typing import Dict, Union
-
 import numpy as np
 import pymc as pm
 import xarray as xr
@@ -17,7 +15,7 @@ class Family:
         The name of the family. It can be any string.
     likelihood : Likelihood
         A `bambi.families.Likelihood` instance specifying the model likelihood function.
-    link : str or dict[str, str or Link]
+    link : str or dict of str to (str or Link)
         The link function that's used for every parameter in the likelihood function.
         Keys are the names of the parameters and values are the link functions.
         These can be a `str` with a name or a `bambi.families.Link` instance.
@@ -60,7 +58,7 @@ class Family:
         "tan_2",
     ]
 
-    def __init__(self, name, likelihood, link: Union[str, Dict[str, Union[str, Link]]]):
+    def __init__(self, name, likelihood, link: str | dict[str, str | Link]):
         self.name = name
         self.likelihood = likelihood
         self.link = link
@@ -143,7 +141,7 @@ def posterior_predictive(self, model, posterior, random_seed, **kwargs):
             the parameters that allow to derive them.
         random_seed : int, RandomState or Generator, optional
             Seed for the random number generator.
-        kwargs :
+        kwargs : dict
             Parameters that are used to get draws but do not appear in the posterior object or
             other configuration parameters.
             For instance, the 'n' in binomial models and multinomial models.
@@ -184,7 +182,10 @@ def log_likelihood(self, model, posterior, data, **kwargs):
             The xarray dataset that contains the draws for all the parameters in the posterior.
             It must contain the parameters that are needed in the distribution of the response, or
             the parameters that allow to derive them.
-        kwargs :
+        data : pd.DataFrame or None
+            A data frame with values for the predictors and the response on which the model's
+            log-likelihood function is evaluated. If omitted, the original dataset is used.
+        kwargs : dict
             Parameters that are used to get draws but do not appear in the posterior object or
             other configuration parameters.
             For instance, the 'n' in binomial models and multinomial models.

bambi/families/likelihood.py

@@ -35,12 +35,12 @@ class Likelihood:
     ----------
     name : str
         Name of the likelihood function. Must be a valid PyMC distribution name.
-    params : Sequence[str]
+    params : sequence of str or None, optional
         The name of the parameters the likelihood function accepts.
-    parent : str
+    parent : str or None, optional
         Optional specification of the name of the mean parameter in the likelihood.
         This is the parameter whose transformation is modeled by the linear predictor.
-    dist : pymc.Distribution or callable
+    dist : pymc.Distribution or callable or None, optional
         Optional custom PyMC distribution that will be used to compute the likelihood.
 
     Notes

bambi/families/link.py

@@ -131,13 +131,13 @@ class Link:
         The name of the link function. If it is a known name, it's not necessary to pass any
         other arguments because functions are already defined internally. If not known, all of
         `link`, `linkinv` and `linkinv_backend` must be specified.
-    link : function
+    link : function or None, optional
         A function that maps the response to the linear predictor. Known as the :math:`g` function
         in GLM jargon. Does not need to be specified when `name` is a known name.
-    linkinv : function
+    linkinv : function or None, optional
         A function that maps the linear predictor to the response. Known as the :math:`g^{-1}`
         function in GLM jargon. Does not need to be specified when `name` is a known name.
-    linkinv_backend : function
+    linkinv_backend : function or None, optional
         Same than `linkinv` but must be something that works with PyMC backend (i.e. it must
         work with PyTensor tensors). Does not need to be specified when `name` is a known
         name.

bambi/formula.py

@@ -10,7 +10,7 @@ class Formula:
 
     Allows to describe a model with multiple formulas. The first formula describes the response
     variable and its predictors. The following formulas describe predictors for other parameters
-    of the likelihood function, allowing distributional models.
+    of the response distribution, allowing distributional models.
 
     Parameters
     ----------
@@ -30,12 +30,12 @@ def check_additionals(self, additionals: Sequence[str]):
 
         Parameters
         ----------
-        additionals : Sequence[str]
+        additionals : sequence of str
             Model formulas that describe model parameters rather than a response variable.
 
         Returns
         -------
-        additionals : Sequence[str]
+        additionals : sequence of str
             If all formulas match the required format, it returns them.
         """
         for additional in additionals:
@@ -63,9 +63,9 @@ def check_additional(self, additional: str):
         if response is None:
             raise ValueError("Additional formulas must contain a response name.")
 
-        # The response is a name, not a function call for example
+        # The response is a name, not a function call, for example
         if not isinstance(response.term.components[0], fm.terms.variable.Variable):
-            raise ValueError("The response must be a name.")
+            raise ValueError("The response must be a name")
 
         self.additionals_lhs.append(response.term.name)
 
@@ -74,7 +74,7 @@ def get_all_formulas(self):
 
         Returns
         -------
-        list
+        list of str
             All the formulas in the instance.
         """
         return [self.main] + list(self.additionals)
@@ -91,19 +91,19 @@ def __repr__(self):
 
 
 def formula_has_intercept(formula: str) -> bool:
-    """Determines if a model formula results in a model with intercept."""
+    """Determines if a model formula describes a model with an intercept."""
     description = fm.model_description(formula)
     return any(isinstance(term, fm.terms.Intercept) for term in description.terms)
 
 
 def check_ordinal_formula(formula: Formula) -> Formula:
-    """Check if a supplied formula can be used with an ordinal model
+    """Check if a supplied formula can be used with an ordinal model.
 
     Ordinal models have the following constrains (for the moment):
-    * A single formula must be passed. This is because Bambi does not support
-    modeling the thresholds as a function of predictors.
-    * The intercept is omitted. This is to avoid non-identifiability issues
-    between the intercept and the thresholds.
+    * A single formula must be passed. This is because Bambi does not support  modeling the
+    thresholds as a function of predictors.
+    * The intercept is omitted. This is to avoid non-identifiability issues between the intercept
+    and the thresholds.
     """
     if len(formula.additionals) > 0:
         raise ValueError("Ordinal families don't accept multiple formulas")