ArviZ Base

1.0.0 · active · verified Thu Apr 16

arviz-base is a Python package that provides core ArviZ features and converters, serving as a fundamental component of the modular ArviZ 1.0 ecosystem. It focuses on data structures, primarily leveraging `xarray.DataTree`, and conversion utilities from various probabilistic programming languages (PPLs). This library, currently at version 1.0.0, is under active development as part of the broader ArviZ refactoring, aiming for increased flexibility and a minimal dependency footprint.

Common errors

```
ModuleNotFoundError: No module named 'xarray'
```
cause The core dependency `xarray` is not installed, which is essential for `arviz-base`'s data structures like `DataTree`.

fix Install xarray: `pip install xarray` or `pip install "arviz-base"` (which should pull `xarray` as a dependency).
```
AttributeError: module 'arviz' has no attribute 'InferenceData'
```
cause Attempting to use the deprecated `arviz.InferenceData` object directly with an ArviZ 1.0+ installation (or `arviz-base`). The `InferenceData` object has been replaced by `xarray.DataTree`.

fix Update your code to use `xarray.DataTree` or `arviz_base`'s conversion functions like `from_dict` or `from_cmdstanpy` to create `DataTree` objects. Refer to the ArviZ migration guide for detailed steps.
```
ValueError: setting an array element with a sequence. The above exception was the direct cause of the following exception: ValueError: could not broadcast input array from shape (X,Y) into shape (Z,)
```
cause This error typically occurs when the input data (e.g., NumPy arrays or dictionaries) provided to conversion functions like `from_dict` or other ArviZ functions do not conform to the expected dimensionality or shape for creating a `DataTree` group.

fix Ensure that the input arrays have consistent shapes and the correct number of dimensions corresponding to the `chain`, `draw`, and variable-specific dimensions expected by ArviZ. For instance, posterior samples usually require `(chain, draw, *variable_dimensions)`.

Warnings

breaking ArviZ 1.0, of which arviz-base is a part, introduces a major refactoring. The central `arviz.InferenceData` object has been replaced by `xarray.DataTree`. Code relying on `InferenceData` attributes or methods will break.
Fix: Migrate your data handling to use `xarray.DataTree` structures and `arviz_base`'s new conversion and extraction functions. Consult the ArviZ migration guide.
gotcha arviz-base is a minimal package focused on data structures and converters. For statistical computations or plotting, you will need `arviz-stats` and `arviz-plots` respectively, or install the overarching `arviz` package with necessary extras.
Fix: If you require statistical summaries or visualizations, install `arviz-stats` (`pip install arviz-stats`) and `arviz-plots` (`pip install arviz-plots`), or install `arviz` with relevant I/O and plotting extras (e.g., `pip install "arviz[netcdf4,matplotlib]"`).
gotcha I/O functionalities for formats like NetCDF, HDF5, or Zarr are provided via optional dependencies. `arviz-base` itself does not have these as hard requirements to maintain a minimal footprint.
Fix: Install the specific I/O backend you need separately, e.g., `pip install netcdf4` or `pip install zarr`. When installing `arviz` (the meta-package), these can be specified as extras, e.g., `pip install "arviz[netcdf4]"`.

Install

pip install arviz-base Install stable version

Imports

arviz_base
wrong:
```
import arviz as az_old; az_old.InferenceData()
```
correct:
```
import arviz_base as az
```
arviz-base uses its own namespace; the old `arviz.InferenceData` has been replaced by `xarray.DataTree` in 1.0.
load_arviz_data
```
from arviz_base import load_arviz_data
```
Used for loading pre-packaged ArviZ example datasets.
from_dict
```
from arviz_base import from_dict
```
Used for converting Python dictionaries to `xarray.DataTree` following ArviZ conventions.

Quickstart

This quickstart demonstrates loading an example dataset using `load_arviz_data` and then extracting data with `extract`. It also shows how to convert raw Python dictionaries containing NumPy arrays into an ArviZ-compatible `xarray.DataTree` using `from_dict`.

import arviz_base as az
import numpy as np

# Load an example dataset provided by ArviZ Base
idata = az.load_arviz_data("centered_eight")
print(f"Loaded DataTree with groups: {list(idata.keys())}")

# Extract a specific group, e.g., 'posterior', combining chain and draw dimensions
extracted_data = az.extract(idata, group="posterior")
print(f"\nExtracted posterior data shape: {extracted_data.sizes}")

# Convert a simple dictionary to a DataTree
my_data = {
    "posterior": {
        "alpha": np.random.normal(0, 1, size=(4, 500)),
        "beta": np.random.normal(0, 0.5, size=(4, 500))
    }
}
custom_idata = az.from_dict(my_data)
print(f"\nCustom DataTree with groups: {list(custom_idata.keys())}")

view raw JSON →