PyMC

https://www.pymc.io/projects/docs
Admin
PyMC is a probabilistic programming library for Bayesian statistical modeling and inference using...
Tokens:1,501,409
Snippets:11,429
Trust Score:9.1
Update:4 months ago
Show doc for...
Tokens:
Raw
### Latent Kronecker GP Example Setup

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/gp/gp.html

Example demonstrating the setup of a Latent Gaussian Process with a Kronecker product kernel in PyMC. It defines input data for two dimensions and specifies covariance functions.

```python
# One dimensional column vectors of inputs
X1 = np.linspace(0, 1, 10)[:, None]
X2 = np.linspace(0, 2, 5)[:, None]
Xs = [X1, X2]
with pm.Model() as model:
    # Specify the covariance functions for each Xi
```

--------------------------------

### Alternative Development Environment Setup

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/pr_tutorial.md.txt

Alternatively, set up the development environment using pip install for editable mode and requirements-dev.txt.

```bash
pip install -e .
pip install -r requirements-dev.txt
```

--------------------------------

### Gitpod Terminal Environment

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/using_gitpod.md.txt

This is an example of the terminal prompt in a Gitpod environment after the initial setup is complete.

```console
(base) gitpod@reshamas-pymc-0ygu5rf74md:/workspace/pymc$

```

--------------------------------

### Install pre-commit

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/python_style.md.txt

Install the pre-commit tool to enforce code quality checks locally before committing.

```bash
pip install pre-commit
```

--------------------------------

### Install and Run Pre-commit Checks

Source: https://www.pymc.io/projects/docs/en/stable/contributing/pr_tutorial.html

Install the pre-commit package and run all checks manually. It can also be installed to run automatically before each commit.

```bash
pip install pre-commit
pre-commit run --all      # 👈 to run it manually
pre-commit install        # 👈 to run it automatically before each commit
```

--------------------------------

### Basic Model Comparison Setup

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/model_comparison.ipynb.txt

Illustrates the initial setup for comparing models, including necessary imports and data preparation. This is a foundational step for any model comparison task.

```python
import pymc as pm
import numpy as np
import arviz as az
import matplotlib.pyplot as plt

np.random.seed(42)

# Data
N = 100
x = np.random.rand(N)
y = 1 + 2 * x + np.random.randn(N) * 0.5

# Model 1: Simple Linear Regression
with pm.Model() as model1:
    a = pm.Normal('a', mu=0, sigma=10)
    b = pm.Normal('b', mu=0, sigma=10)
    sigma = pm.HalfNormal('sigma', sigma=1)
    mu = a + b * x
    y_obs = pm.Normal('y_obs', mu=mu, sigma=sigma, observed=y)

# Model 2: Linear Regression with different priors
with pm.Model() as model2:
    a_ = pm.Normal('a', mu=0, sigma=5)
    b_ = pm.Normal('b', mu=0, sigma=5)
    sigma_ = pm.HalfNormal('sigma', sigma=2)
    mu_ = a_ + b_ * x
    y_obs_ = pm.Normal('y_obs', mu=mu_, sigma=sigma_, observed=y)

# Model 3: Adding an interaction term
with pm.Model() as model3:
    a__ = pm.Normal('a', mu=0, sigma=10)
    b__ = pm.Normal('b', mu=0, sigma=10)
    c__ = pm.Normal('c', mu=0, sigma=10)
    sigma__ = pm.HalfNormal('sigma', sigma=1)
    mu__ = a__ + b__ * x + c__ * x**2
    y_obs__ = pm.Normal('y_obs', mu=mu__, sigma=sigma__, observed=y)
```

--------------------------------

### BaseTrace setup method

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/backends/base.html

Performs chain-specific setup for the trace. It takes the expected number of draws, the chain number, and optional sampler statistics.

```python
def setup(self, draws, chain, sampler_vars=None) -> None:
    """Perform chain-specific setup.

    Parameters
    ----------
    draws: int
        Expected number of draws
    chain: int
        Chain number
    sampler_vars: list of dictionaries (name -> dtype), optional
        Diagnostics / statistics for each sampler
    """
    self._set_sampler_vars(sampler_vars)
    self._is_base_setup = True
```

--------------------------------

### Model Sampling with Custom Initialization

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/pymc_pytensor.ipynb.txt

Shows how to provide custom initial values for the model parameters before sampling begins. This can be useful for guiding the sampler or starting from a known good state.

```python
initial_values = {"mu": 0.5, "sigma": 0.5}
with model:
    # Draw posterior samples with custom initial values
    trace_init = pm.sample(2000, tune=1000, start=initial_values, cores=1)
```

--------------------------------

### setup

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/backends/base.html

Performs chain-specific setup for the backend, initializing necessary parameters for sampling. It takes the expected number of draws, the chain number, and optional sampler statistics as input.

```APIDOC
## setup

### Description
Perform chain-specific setup.

### Parameters
* **draws** (int) - Expected number of draws
* **chain** (int) - Chain number
* **sampler_vars** (list of dictionaries (name -> dtype), optional) - Diagnostics / statistics for each sampler
```

--------------------------------

### Install Development Dependencies

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/running_the_test_suite.md.txt

Installs the necessary development dependencies for running the test suite. This should be the first step before executing any tests.

```bash
pip install -r requirements-dev.txt
```

--------------------------------

### Install NetworkX using Pip

Source: https://www.pymc.io/projects/docs/en/stable/api/model/generated/pymc.model_graph.model_to_networkx.html

Install the networkx library using the pip package manager.

```bash
pip install networkx
```

--------------------------------

### Run Pre-commit Checks and Install Hook

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/pr_tutorial.md.txt

Install pre-commit and run its checks manually or set it up to run automatically before each commit.

```bash
pip install pre-commit
pre-commit run --all      # ðŸ‘ˆ to run it manually
pre-commit install        # ðŸ‘ˆ to run it automatically before each commit
```

--------------------------------

### Example of cross-reference to another project (ArviZ)

Source: https://www.pymc.io/projects/docs/en/stable/contributing/jupyter_style.html

This example demonstrates linking to the 'working_with_InferenceData' section in the ArviZ documentation, using 'arviz' as the project key.

```markdown
{ref}`how to use InferenceData <arviz:working_with_InferenceData>`
```

--------------------------------

### Install Nutpie Sampler

Source: https://www.pymc.io/projects/docs/en/stable/_sources/installation.md.txt

Installs the Nutpie library, which provides a faster sampling backend using Numba and Rust.

```console
conda install -c conda-forge nutpie
```

--------------------------------

### Install BlackJAX Sampler

Source: https://www.pymc.io/projects/docs/en/stable/_sources/installation.md.txt

Installs the BlackJAX library, an alternative sampler that can be used with PyMC.

```console
conda install blackjax
```

--------------------------------

### Install JAX Backend (NumPyro)

Source: https://www.pymc.io/projects/docs/en/stable/_sources/installation.md.txt

Installs the NumPyro library, which is required for JAX-based sampling with PyMC.

```console
conda install numpyro
```

--------------------------------

### Install Documentation Dependencies and Local PyMC

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/build_docs.md.txt

Installs the necessary dependencies for building the documentation and installs the PyMC package in editable mode.

```shell
conda env create -f conda-envs/environment-docs.yml

pip install -e .
```

--------------------------------

### Install Bambi Library

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/GLM_linear.ipynb.txt

Installs the Bambi library using pip if it is not already installed. This is a prerequisite for using the Bambi formula interface.

```python
try:
    import bambi as bmb
except ImportError:
    !{sys.executable} -m pip install -q --upgrade bambi
    import bambi as bmb
```

--------------------------------

### Marginal GP Constructor and Example

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/gp/gp.html

Initializes a Marginal Gaussian process with optional mean and covariance functions. Includes an example of setting up input data.

```python
@conditioned_vars(["X", "y", "sigma"])
class Marginal(Base):
    R"""
    Marginal Gaussian process.

    The `gp.Marginal` class is an implementation of the sum of a GP
    prior and additive noise.  It has `marginal_likelihood`, `conditional`
    and `predict` methods.  This GP implementation can be used to
    implement regression on data that is normally distributed.  For more
    information on the `marginal_likelihood`, `conditional`
    and `predict` methods, see their docstrings.

    Parameters
    ----------
    mean_func : Mean, default ~pymc.gp.mean.Zero
        The mean function.
    cov_func : 2D array-like, or Covariance, default ~pymc.gp.cov.Constant
        The covariance function.

    Examples
    --------
    .. code-block:: python

        # A one dimensional column vector of inputs.
        X = np.linspace(0, 1, 10)[:, None]


```

--------------------------------

### Setup NDArray Backend for Sampling

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/backends/ndarray.html

Perform chain-specific setup for the NDArray backend. This method initializes the storage for samples based on the expected number of draws and chain information. It can also handle pre-existing samples by concatenating new arrays.

```python
def setup(self, draws, chain, sampler_vars=None) -> None:
    """Perform chain-specific setup.

    Parameters
    ----------
    draws: int
        Expected number of draws
    chain: int
        Chain number
    sampler_vars: list of dicts
        Names and dtypes of the variables that are
        exported by the samplers.
    """
    super().setup(draws, chain, sampler_vars)

    self.chain = chain
    if self.samples:  # Concatenate new array if chain is already present.
        old_draws = len(self)
        self.draws = old_draws + draws
        self.draw_idx = old_draws
        for varname, shape in self.var_shapes.items():
            old_var_samples = self.samples[varname]
            new_var_samples = np.zeros((draws, *shape), self.var_dtypes[varname])
            self.samples[varname] = np.concatenate((old_var_samples, new_var_samples), axis=0)
    else:  # Otherwise, make array of zeros for each variable.
        self.draws = draws
        for varname, shape in self.var_shapes.items():
            self.samples[varname] = np.empty((draws, *shape), dtype=self.var_dtypes[varname])

    if sampler_vars is None:
        return

    if self._stats is None:
        self._stats = []
        for sampler in sampler_vars:
            data: dict[str, np.ndarray] = {}
            self._stats.append(data)
            for varname, dtype in sampler.items():
                data[varname] = np.zeros(draws, dtype=dtype)
    else:
        for data, vars in zip(self._stats, sampler_vars):
            if vars.keys() != data.keys():
                raise ValueError("Sampler vars can't change")
            for varname, dtype in vars.items():
                old = data[varname]
                new = np.zeros(draws, dtype=dtype)
                data[varname] = np.concatenate([old, new])
```

--------------------------------

### Example of cross-reference to a target within the current project

Source: https://www.pymc.io/projects/docs/en/stable/contributing/jupyter_style.html

This is a concrete example of linking to a notebook with the anchor ID 'GP-Kron', displaying 'Kronecker product' as the explicit text.

```markdown
{ref}`Kronecker product <GP-Kron>`
```

--------------------------------

### SMC Sampler Initialization

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/smc/sampling.html

Initializes the SMC sampler with specified parameters. Handles multiprocessing, kernel setup, and prepares starting points for chains. Ensure the number of start dictionaries matches the number of chains if providing custom start points.

```python
if cores is None:
        cores = _cpu_count()

    if chains is None:
        chains = max(2, cores)
    else:
        cores = min(chains, cores)

    compile_kwargs = resolve_backend_compile_kwargs(backend, compile_kwargs)
    kernel_kwargs["compile_kwargs"] = compile_kwargs

    random_seed = _get_seeds_per_chain(random_state=random_seed, chains=chains)

    model = modelcontext(model)

    logger.info("Initializing SMC sampler...")

    mp_ctx = _initialize_multiprocessing_context(mp_ctx, mode=compile_kwargs.get("mode"))
    joined_blas_limiter, cores, num_blas_cores_per_worker = setup_cores_blas_cores(
        blas_cores, chains, cores, mp_ctx
    )

    t1 = time.time()

    rngs = [np.random.default_rng(seed) for seed in random_seed]

    with model:
        smc_kernel = kernel(
            draws=draws,
            start=None,
            model=model,
            random_seed=rngs[0].integers(2**30),
            **kernel_kwargs,
        )

    # Prepare start points for each chain
    start_points: list[dict | None]
    if start is None:
        start_points = [None] * chains
    elif isinstance(start, dict):
        start_points = [start] * chains
    else:
        if len(start) != chains:
            raise ValueError(f"Number of start dicts must match number of chains ({chains})")
        start_points = start

    parallel = cores > 1 and chains > 1

    traces = []
    sample_stats = []
    sample_settings = []

    if parallel:
        logger.info(
            f"Sampling {chains} chain{'s' if chains > 1 else ''} "
            f"in {cores} job{'s' if cores > 1 else ''}"
        )

        results = []
        with joined_blas_limiter():
            with ParallelSMCSampler(
                kernel=smc_kernel,
                chains=chains,
                cores=cores,
                rngs=rngs,
                start_points=start_points,
                progressbar=progressbar,
                progressbar_theme=progressbar_theme,
                mp_ctx=mp_ctx,
                blas_cores=num_blas_cores_per_worker,
            ) as sampler:
                for result in sampler:
                    results.append(result)

```

--------------------------------

### ZarrChain.setup

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/backends/zarr.html

Initializes the ZarrChain backend with sampling parameters.

```APIDOC
## ZarrChain.setup

### Description
Initializes the ZarrChain backend with the total number of draws, chain identifier, and sampler variables.

### Method
setup

### Parameters
#### Path Parameters
- **draws** (int) - The total number of draws for the chain.
- **chain** (int) - The identifier for the current chain.
- **sampler_vars** (Sequence[dict] | None) - A sequence of dictionaries containing sampler variables.
```

--------------------------------

### BaseTrace.setup

Source: https://www.pymc.io/projects/docs/en/stable/_sources/api/generated/classmethods/pymc.backends.base.BaseTrace.setup.rst.txt

The setup method is a class method used to initialize and configure the trace backend before sampling begins. It prepares the necessary structures for storing trace data.

```APIDOC
## BaseTrace.setup

### Description
Initializes and configures the trace backend for storing sampling results.

### Method
classmethod

### Parameters
This method does not take any explicit parameters beyond `cls` (the class itself) and `kwargs` which are passed to the backend's initialization.

### Returns
An instance of the trace backend configured for sampling.

### Example
```python
# Example usage within a PyMC model context (conceptual)
# This method is typically called internally by PyMC's sampling functions.
# trace = BaseTrace.setup(model=my_model, **backend_kwargs)
```
```

--------------------------------

### ZarrChain.setup

Source: https://www.pymc.io/projects/docs/en/stable/_sources/api/generated/classmethods/pymc.backends.zarr.ZarrChain.setup.rst.txt

The `setup` method is a class method used to initialize and configure the Zarr backend for storing inference results. It prepares the Zarr store for saving trace data.

```APIDOC
## ZarrChain.setup

### Description
Initializes and configures the Zarr backend for storing inference results. This method prepares the Zarr store for saving trace data.

### Method
`setup`

### Parameters
This method does not take any explicit parameters in its signature as presented, but it operates on the class context to prepare the Zarr store.

### Returns
This method typically returns `None` or a reference to the initialized Zarr store, depending on the internal implementation details not fully exposed in this documentation stub.
```

--------------------------------

### Gaussian GLM Example

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/GLM_linear.ipynb.txt

Demonstrates a basic Gaussian GLM. Ensure you have PyMC and ArviZ installed. This model assumes a normal distribution for the response variable.

```python
import pymc as pm
import numpy as np
import arviz as az

# Generate synthetic data
np.random.seed(0)
N = 100
X = np.random.rand(N, 2)
y = X @ np.array([1.5, -0.8]) + np.random.normal(0, 1, N)

# Build the model
with pm.Model() as model:
    # Priors for regression coefficients
    beta = pm.Normal("beta", mu=0, sigma=10, shape=X.shape[1])
    # Prior for standard deviation
    sigma = pm.HalfNormal("sigma", sigma=1)

    # Expected value of outcome
    mu = pm.Deterministic("mu", X @ beta)

    # Likelihood (sampling distribution) of the outcome
    Y_obs = pm.Normal("Y_obs", mu=mu, sigma=sigma, observed=y)

    # Sample from the posterior
    idata = az.from_pymc3(pm.sample(1000, tune=1000, cores=1, return_inferencedata=True))

print(az.summary(idata, hdi_prob=0.95))
```

--------------------------------

### Get Initial Point for Sampling

Source: https://www.pymc.io/projects/docs/en/stable/learn/core_notebooks/pymc_pytensor.html

Retrieve a default starting point for samplers using `model.initial_point()`. This is useful for providing input to compiled log-probability functions.

```python
point = model.initial_point()
```

--------------------------------

### Initializing SMC Kernel

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/smc/kernels.html

Initializes the SMC kernel for sampling. It sets the starting point, random number generator, resets the state, and performs kernel-specific setup.

```python
    def initialize(self, start: dict | None, rng: np.random.Generator) -> None:
        """Initialize the kernel for sampling.

        Parameters
        ----------
        start : dict or None
            Starting point in parameter space, or None to sample from prior.
        rng : np.random.Generator
            Random number generator for this chain.
        """
        self.start = start
        self.rng = rng
        self._reset_state()
        self.set_rng(rng)
        self._initialize_kernel()
        self.setup_kernel()
```

--------------------------------

### Access Posterior Predictive Samples

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/posterior_predictive.ipynb.txt

After drawing posterior predictive samples, you can access them directly from the `ppc` object. This example demonstrates how to get the simulated data for the 'y' variable.

```python
y_pred = ppc['y']
```

--------------------------------

### Performing a Posterior Predictive Test

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/posterior_predictive.ipynb.txt

This example demonstrates how to use `az.summary` to get a quantitative summary of the posterior predictive distribution of a statistic, including its relation to the observed value.

```python
az.summary(idata, var_names=['y'], extend=True)

```

--------------------------------

### PyMC ZarrChain Setup Method

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/backends/zarr.html

Initializes the ZarrChain with drawing and chain information. It sets up the number of draws and determines when to flush the buffer.

```python
def setup(self, draws: int, chain: int, sampler_vars: Sequence[dict] | None):
        self.chain = chain
        self.total_draws = draws
        self.draws_until_flush = min([self.draws_per_chunk, draws - self.draw_idx])
        self.clear_buffers()
```

--------------------------------

### Get Initial Point for Model

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/pymc_pytensor.ipynb.txt

Retrieves the initial point dictionary used by samplers for a given model. This is useful for providing starting values to the compiled logp function.

```python
point = model.initial_point()
point
```

--------------------------------

### Import Libraries and Setup

Source: https://www.pymc.io/projects/docs/en/stable/learn/core_notebooks/posterior_predictive.html

Imports necessary libraries like ArviZ, Matplotlib, NumPy, Xarray, SciPy, and PyMC. Also prints the PyMC version and sets up ArviZ style and a random number generator.

```python
import arviz as az
import matplotlib.pyplot as plt
import numpy as np
import xarray as xr

from scipy.special import expit as logistic

import pymc as pm

print(f"Running on PyMC v{pm.__version__}")
```

```python
az.style.use("arviz-variat")

RANDOM_SEED = 58
ng = np.random.default_rng(RANDOM_SEED)


def standardize(series):
    """Standardize a pandas series"""
    return (series - series.mean()) / series.std()
```

--------------------------------

### Load Example Data

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/model_comparison.ipynb.txt

Loads a dataset for model comparison. Ensure the data is preprocessed and ready for model fitting.

```python
import pymc as pm
import arviz as az
import numpy as np
import pandas as pd

# Load data
data = pd.read_csv("../data/radon.csv")

# Preprocess data
# Remove rows with missing values
data = data.dropna()

# Select relevant columns
data = data["id"] = data["id"].astype(str)

# Create a dictionary of datasets
datasets = {
    "radon": data
}
```

--------------------------------

### Mixture of (5 x 3) Normal Variables

Source: https://www.pymc.io/projects/docs/en/stable/api/distributions/generated/pymc.Mixture.html

Example of a more complex mixture where component distributions have shapes and the mixture itself is an array. This setup allows for vectorized operations across multiple dimensions.

```python
import pymc as pm
import numpy as np

with pm.Model() as model:
    # w is a stack of 5 independent size 3 weight vectors
    # If shape was `(3,)`, the weights would be shared across the 5 replication dimensions
    w = pm.Dirichlet("w", a=np.ones(3), shape=(5, 3))

    # Each of the 3 mixture components has an independent mean
    mu = pm.Normal("mu", mu=np.arange(3), sigma=1, shape=3)

    # These two forms are equivalent, but the second benefits from vectorization
    components = [
        pm.Normal.dist(mu=mu[0], sigma=1, shape=(5,)),
        pm.Normal.dist(mu=mu[1], sigma=1, shape=(5,)),
        pm.Normal.dist(mu=mu[2], sigma=1, shape=(5,)),
    ]
    components = pm.Normal.dist(mu=mu, sigma=1, shape=(5, 3))

    # The mixture is an array of 5 elements
    # Each element can be thought of as an independent scalar mixture of 3
    # components with different means
    like = pm.Mixture("like", w=w, comp_dists=components, observed=data)
```

--------------------------------

### Setting up a PyMC Model for Sampling Examples

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/sampling/forward.html

This code block sets up a basic PyMC model with several variables and performs initial sampling. It configures logging and uses specific keyword arguments for sampling.

```python
from logging import getLogger
import pymc as pm

# Some environments like google colab suppress
# the default logging output of PyMC
getLogger("pymc").setLevel("INFO")

kwargs = {"progressbar": False, "random_seed": 0}

with pm.Model() as model:
    x = pm.Normal("x")
    y = pm.Normal("y")
    z = pm.Normal("z", x + y**2)
    det = pm.Deterministic("det", pm.math.exp(z))
    obs = pm.Normal("obs", det, 1, observed=[20])

    idata = pm.sample(tune=10, draws=10, chains=2, **kwargs)
```

--------------------------------

### Setup Cores and BLAS Cores for Sampling

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/sampling/mcmc.html

Configures the number of CPU cores and BLAS threads for parallel sampling. Handles 'auto' setting for BLAS cores and ensures compatibility with different multiprocessing start methods.

```python
def setup_cores_blas_cores(
    blas_cores: int | None | str,
    chains: int,
    cores: int,
    mp_ctx: multiprocessing.context.BaseContext,
) -> tuple[Callable[[], Any], int, int | None]:
    if isinstance(blas_cores, str) and blas_cores != "auto":
        raise ValueError(
            f"Invalid argument `blas_cores`, must be int, 'auto' or None: {blas_cores}"
        )
    if blas_cores == "auto":
        blas_cores = cores

    cores = min(cores, chains)

    num_blas_cores_per_worker: int | None
    joined_blas_limiter: Callable[[], Any]

    if blas_cores is None:
        joined_blas_limiter = contextlib.nullcontext
        num_blas_cores_per_worker = None

    elif isinstance(blas_cores, int):
        if mp_ctx.get_start_method() == "fork":
            # https://github.com/pymc-devs/pymc/issues/7354
            joined_blas_limiter = contextlib.nullcontext
        else:

            def joined_blas_limiter():
                return threadpool_limits(limits=blas_cores)

        num_blas_cores_per_worker = blas_cores // cores
    else:
        raise ValueError(
            f"Invalid argument `blas_cores`, must be int, 'auto' or None: {blas_cores}"
        )
    return joined_blas_limiter, cores, num_blas_cores_per_worker
```

--------------------------------

### Ordered Logistic Regression Example

Source: https://www.pymc.io/projects/docs/en/stable/api/distributions/generated/pymc.OrderedLogistic.html

Demonstrates how to use the OrderedLogistic distribution for regression on ordinal data. It includes data generation, model definition with ordered cutpoints, sampling, and plotting the results. Ensure PyMC and Matplotlib are installed.

```python
import pymc as pm
import numpy as np
import matplotlib.pyplot as plt

# Generate data for a simple 1 dimensional example problem
n1_c = 300; n2_c = 300; n3_c = 300
cluster1 = np.random.randn(n1_c) + -1
cluster2 = np.random.randn(n2_c) + 0
cluster3 = np.random.randn(n3_c) + 2

x = np.concatenate((cluster1, cluster2, cluster3))
y = np.concatenate((1*np.ones(n1_c),
                    2*np.ones(n2_c),
                    3*np.ones(n3_c))) - 1

# Ordered logistic regression
with pm.Model() as model:
    cutpoints = pm.Normal("cutpoints", mu=[-1,1], sigma=10, shape=2,
                          transform=pm.distributions.transforms.ordered)
    y_ = pm.OrderedLogistic("y", cutpoints=cutpoints, eta=x, observed=y)
    idata = pm.sample()

# Plot the results
plt.hist(cluster1, 30, alpha=0.5)
plt.hist(cluster2, 30, alpha=0.5)
plt.hist(cluster3, 30, alpha=0.5)
posterior = idata.posterior.stack(sample=("chain", "draw"))
plt.hist(posterior["cutpoints"][0], 80, alpha=0.2, color='k')
plt.hist(posterior["cutpoints"][1], 80, alpha=0.2, color='k')

plt.show()
```

--------------------------------

### Set up Model Comparison

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/model_comparison.ipynb.txt

Initialize a ModelComparison object with a list of models and their corresponding data. This is the first step in comparing models.

```python
from pymc.stats.graph_viz import ModelComparison
from pymc.model_comparison import compare

# Assuming 'models' is a dictionary where keys are model names and values are PyMC models
# and 'idata_list' is a list of ArviZ InferenceData objects for each model

# Example: 
# models = {"model_a": model_a, "model_b": model_b}
# idata_list = [idata_a, idata_b]

# For demonstration, let's assume idata_list is already populated
# mc = ModelComparison(models, idata_list)

# To use the compare function directly, you need InferenceData objects
# For example, if you have idata_a and idata_b:
# comparison_results = compare({'model_a': idata_a, 'model_b': idata_b})

```

--------------------------------

### Define MatrixNormal Distribution

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/distributions/multivariate.html

Example of defining a MatrixNormal distribution with specified mean, row covariance, and column covariance matrices. This setup is useful when the covariance structure of a matrix-valued random variable has distinct row and column dependencies.

```python
import pymc as pm
import numpy as np
import pytensor.tensor as pt

with pm.Model() as model:
    colcov = np.array([[1.0, 0.5], [0.5, 2]])
    rowcov = np.array([[1, 0, 0], [0, 4, 0], [0, 0, 16]])
    m = rowcov.shape[0]
    n = colcov.shape[0]
    mu = np.zeros((m, n))
    vals = pm.MatrixNormal("vals", mu=mu, colcov=colcov, rowcov=rowcov)
```

--------------------------------

### Mixture of Poisson Distributions Example

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/distributions/mixture.html

Demonstrates how to create a mixture model with two Poisson distributions. It shows the setup for mixture weights and component distributions, including the use of `.dist()` for creating distributions without adding them as explicit random variables.

```python
with pm.Model() as model:
    w = pm.Dirichlet("w", a=np.array([1, 1]))  # 2 mixture weights

    lam1 = pm.Exponential("lam1", lam=1)
    lam2 = pm.Exponential("lam2", lam=1)

    # As we just need the logp, rather than add a RV to the model, we need to call `.dist()`
    # These two forms are equivalent, but the second benefits from vectorization
    components = [
        pm.Poisson.dist(mu=lam1),
        pm.Poisson.dist(mu=lam2),
    ]
    # `shape=(2,)` indicates 2 mixture components
    components = pm.Poisson.dist(mu=pm.math.stack([lam1, lam2]), shape=(2,))

    like = pm.Mixture("like", w=w, comp_dists=components, observed=data)
```

--------------------------------

### MH Kernel Setup

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/smc/kernels.html

Sets up the proposal distribution for the MH kernel. Initializes proposal scales based on the number of dimensions and a heuristic for optimal acceptance rate.

```python
def setup_kernel(self):
    """Proposal dist is just a Multivariate Normal with unit identity covariance.

    Dimension specific scaling is provided by `self.proposal_scales` and set in `self.tune()`.
    """
    ndim = self.tempered_posterior.shape[1]
    self.proposal_scales = np.full(self.draws, min(1, 2.38**2 / ndim))

```

--------------------------------

### NDArray.setup

Source: https://www.pymc.io/projects/docs/en/stable/api/generated/classmethods/pymc.backends.NDArray.setup.html

Performs chain-specific setup for the NDArray backend, initializing expected draws, chain number, and sampler variables.

```APIDOC
## NDArray.setup

### Description
Performs chain-specific setup for the NDArray backend. This method is used to initialize the backend with the expected number of draws, the current chain number, and optionally, the variables exported by the samplers.

### Method
`setup(_draws_, _chain_, _sampler_vars_=None_)

### Parameters
#### Path Parameters
- **draws** (int) - Required - Expected number of draws.
- **chain** (int) - Required - Chain number.
- **sampler_vars** (list of dicts) - Optional - Names and dtypes of the variables that are exported by the samplers.
```

--------------------------------

### PyMC Model Initialization with Context Manager

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/model/core.html

Demonstrates how to define a PyMC model and its variables using a 'with' statement. This is the recommended approach for most use cases.

```python
import pymc as pm

with pm.Model() as model:
    x = pm.Normal("x")
```

--------------------------------

### Switch to Feature Branch

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/pr_tutorial.md.txt

Switch to your already created feature branch to begin development.

```bash
git checkout my-feature   # no -b flag because the branch is already created
```

--------------------------------

### Install NetworkX using Conda

Source: https://www.pymc.io/projects/docs/en/stable/api/model/generated/pymc.model_graph.model_to_networkx.html

Install the networkx library using the conda package manager.

```bash
conda install networkx
```

--------------------------------

### Model Sampling with Custom Initialization Methods

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/pymc_pytensor.ipynb.txt

Illustrates how to use different methods for initializing the model parameters, such as 'advi' (Automatic Differentiation Variational Inference). This can provide a good starting point for MCMC.

```python
with model:
    # Initialize with ADVI and then sample
    approx = pm.fit(10000, method='advi', obj_optimizer=pm.adagrad(learning_rate=0.01))
    trace_init_method = pm.sample(2000, tune=1000, start=approx.sample(), cores=1)
```

--------------------------------

### Authorship Log Example 1

Source: https://www.pymc.io/projects/docs/en/stable/contributing/jupyter_style.html

Example of how to format the Authors section for logging contributions to a notebook.

```markdown
## Authors

* Authored by Chris Fonnesbeck in May, 2017 ([pymc#2124](https://github.com/pymc-devs/pymc/pull/2124))
* Updated by Colin Carroll in June, 2018 ([pymc#3049](https://github.com/pymc-devs/pymc/pull/3049))
* Updated by Alex Andorra in January, 2020 ([pymc#3765](https://github.com/pymc-devs/pymc/pull/3765))
* Updated by Oriol Abril in June, 2020 ([pymc#3963](https://github.com/pymc-devs/pymc/pull/3963))
* Updated by Farhan Reynaldo in November 2021 ([pymc-examples#246](https://github.com/pymc-devs/pymc-examples/pull/246))


```

--------------------------------

### Install Development Dependencies

Source: https://www.pymc.io/projects/docs/en/stable/contributing/running_the_test_suite.html

Installs the necessary additional dependencies required for running the PyMC test suite.

```bash
pip install -r requirements-dev.txt

```

--------------------------------

### Activate Environment and Install PyMC

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/pr_tutorial.md.txt

Activate the created conda environment and install PyMC in editable mode.

```bash
conda activate pymc-dev
pip install -e .
```

--------------------------------

### Visualize Model Comparison with ArviZ

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/model_comparison.ipynb.txt

This example uses the ArviZ library to visualize the comparison results, providing a clear graphical representation of model performance based on WAIC and LOO.

```python
import arviz as az

# Assuming waic_result and loo_result are already computed
# and stored in a dictionary like comparison_dict above

az.plot_compare(comparison_df)
```

--------------------------------

### Load Example Data

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/model_comparison.ipynb.txt

Loads the 'radon' dataset, commonly used for hierarchical modeling examples in PyMC.

```python
import pymc as pm
import numpy as np
import pandas as pd
import arviz as az

# Load the radon dataset
radon = pd.read_csv(
    "https://raw.githubusercontent.com/pymc-labs/pymc-resources/main/data/radon.csv"
)
radon = radon.set_index("id")
radon = radon.loc[radon.loc[:, "state"] == "CA", :]
radon["log_radon"] = np.log(radon["radon"])
radon["county_idx"] = pd.Categorical(radon["countyname"]).codes

# Select a subset of counties for faster computation
counties = radon["countyname"].unique()
counties_idx = counties[[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]]
radon_subset = radon[radon["countyname"].isin(counties_idx)]

# Define county index for the subset
radon_subset["county_idx"] = pd.Categorical(radon_subset["countyname"]).codes

# Define variables for the model
log_radon = radon_subset["log_radon"].values
county_idx = radon_subset["county_idx"].values
num_counties = len(counties_idx)

```

--------------------------------

### Setting up a MarginalKron GP

Source: https://www.pymc.io/projects/docs/en/stable/api/gp/generated/pymc.gp.MarginalKron.html

Demonstrates how to initialize and use the MarginalKron GP for a one-dimensional input space with two covariance functions. This setup is suitable for data on a full grid.

```python
import pymc as pm
import numpy as np

# One dimensional column vectors of inputs
X1 = np.linspace(0, 1, 10)[:, None]
X2 = np.linspace(0, 2, 5)[:, None]
Xs = [X1, X2]
y = np.random.randn(len(X1) * len(X2))  # toy data

with pm.Model() as model:
    # Specify the covariance functions for each Xi
    cov_func1 = pm.gp.cov.ExpQuad(1, ls=0.1)  # Must accept X1 without error
    cov_func2 = pm.gp.cov.ExpQuad(1, ls=0.3)  # Must accept X2 without error

    # Specify the GP.  The default mean function is `Zero`.
    gp = pm.gp.MarginalKron(cov_funcs=[cov_func1, cov_func2])

    # Place a GP prior over the function f.
    sigma = pm.HalfCauchy("sigma", beta=3)
    y_ = gp.marginal_likelihood("y", Xs=Xs, y=y, sigma=sigma)

    # ...

```

--------------------------------

### adadelta Optimizer Example

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/variational/updates.html

Demonstrates the usage of the adadelta optimizer for calculating parameter updates. It shows how to instantiate the optimizer and apply it to a variable.

```python
>>> a = pytensor.shared(1.)
>>> b = a*2
>>> updates = adadelta(b, [a], learning_rate=.01)
>>> isinstance(updates, dict)
True
>>> optimizer = adadelta(learning_rate=.01)
>>> callable(optimizer)
True
>>> updates = optimizer(b, [a])
>>> isinstance(updates, dict)
True
```

--------------------------------

### Check Zarr Availability

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/backends/zarr.html

Raises a RuntimeError if the zarr library is not installed. Ensure zarr is installed before creating ZarrTrace instances.

```python
if not _zarr_available:
    raise RuntimeError("You must install zarr to be able to create ZarrTrace instances")
```

--------------------------------

### BaseTrace.setup

Source: https://www.pymc.io/projects/docs/en/stable/api/generated/classmethods/pymc.backends.base.BaseTrace.setup.html

Performs chain-specific setup for trace objects. This method is called internally by PyMC during sampling to prepare the trace for a specific chain.

```APIDOC
## BaseTrace.setup

### Description
Perform chain-specific setup.

### Method
`setup(_draws_, _chain_, _sampler_vars_=None_)

### Parameters
#### Path Parameters
- **_draws_** (int) - Expected number of draws
- **_chain_** (int) - Chain number
- **_sampler_vars_** (list of dictionaries (name - > dtype), optional) - Diagnostics / statistics for each sampler
```

--------------------------------

### StudentT Distribution Example

Source: https://www.pymc.io/projects/docs/en/stable/_modules/pymc/distributions/continuous.html

Example of defining a Student's T distribution with specified parameters. Ensure PyMC is imported as pm.

```python
x = pm.StudentT("x", nu=15, mu=0, sigma=10)
```

--------------------------------

### Sync Repository and Install PyMC

Source: https://www.pymc.io/projects/docs/en/stable/contributing/using_gitpod.html

Update your local repository with the latest changes from the upstream repository and install the project in editable mode.

```bash
cd /workspace/pymc
git checkout main
git pull upstream main --tags
pip install -e .

```

```text
Obtaining file:///workspace/pymc
Installing build dependencies ... done
Checking if build backend supports build_editable ... done
Getting requirements to build editable ... done
Preparing editable metadata (pyproject.toml) ... done
Requirement already satisfied: arviz>=0.13.0 in /opt/conda/lib/python3.11/site-packages (from pymc==5.1.1+303.g6f8f9eef) (0.15.1) 
...
Building editable for pymc (pyproject.toml) ... done
Created wheel for pymc: filename=pymc-5.1.1+303.g6f8f9eef-0.editable-py3-none-any.whl size=11527 sha256=6211b7149b3ab09813b2badb3010f54d2d4ab014f75054d73f204ac5ea82ed82
Stored in directory: /tmp/pip-ephem-wheel-cache-wmkfx8pd/wheels/73/bf/14/341b7fa040e9af1991e12077c13913921be3069fe3bdf78752
Successfully built pymc
Installing collected packages: pytensor, pymc
Attempting uninstall: pytensor
Found existing installation: pytensor 2.10.1
Uninstalling pytensor-2.10.1:
  Successfully uninstalled pytensor-2.10.1
Successfully installed pymc-5.1.1+303.g6f8f9eef pytensor-2.18.6

```

--------------------------------

### ZarrChain.setup

Source: https://www.pymc.io/projects/docs/en/stable/api/generated/classmethods/pymc.backends.zarr.ZarrChain.setup.html

Performs chain-specific setup for a ZarrChain, specifying the number of draws, the chain identifier, and optionally, diagnostic variables.

```APIDOC
## ZarrChain.setup

### Description
Performs chain-specific setup. This method initializes the necessary structures for storing sampling results for a particular chain.

### Method
`setup`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **draws** (int) - Required - Expected number of draws.
* **chain** (int) - Required - Chain number.
* **sampler_vars** (list of dictionaries (name -> dtype), optional) - Diagnostics / statistics for each sampler.
```

--------------------------------

### Example of cross-reference to a Python object (class)

Source: https://www.pymc.io/projects/docs/en/stable/contributing/jupyter_style.html

This example shows how to reference the HSGP class from the pymc.gp module, displaying only the object name 'HSGP'.

```markdown
{class}`~pymc.gp.HSGP`
```

--------------------------------

### Model Sampling with Custom Logging

Source: https://www.pymc.io/projects/docs/en/stable/_sources/learn/core_notebooks/pymc_pytensor.ipynb.txt

Illustrates how to configure logging during the sampling process. This allows for detailed tracking of sampler progress and potential issues.

```python
import logging
logging.basicConfig(level=logging.INFO)

with model:
    # Draw posterior samples with custom logging
    trace_logging = pm.sample(2000, tune=1000, cores=1)
```

--------------------------------

### Authorship attribution example 2

Source: https://www.pymc.io/projects/docs/en/stable/_sources/contributing/jupyter_style.md.txt

Another example of the 'Authors' section, showing variations in attribution, including adaptations from external sources and multiple PRs.

```markdown
## Authors

* Adapted from chapter 5 of Bayesian Data Analysis 3rd Edition {cite:p}`gelman2013bayesian`
  by Demetri Pananos and Junpeng Lao in June, 2018 ([pymc#3054](https://github.com/pymc-devs/pymc/pull/3054))
* Reexecuted by Ravin Kumar with PyMC 3.6 in March, 2019 ([pymc#3397](https://github.com/pymc-devs/pymc/pull/3397))
* Reexecuted by Alex Andorra and Michael Osthege with PyMC 3.9 in June, 2020 ([pymc#3955](https://github.com/pymc-devs/pymc/pull/3955))
* Updated by Raúl Maldonado in 2021 ([pymc-examples#24](https://github.com/pymc-devs/pymc-examples/pull/24), [pymc-examples#45](https://github.com/pymc-devs/pymc-examples/pull/45) and [pymc-examples#147](https://github.com/pymc-devs/pymc-examples/pull/147))
```
Tokens:
Raw