Skip to content

Proofreading docs #2502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aloctavodia wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Proofreading docs #2502

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
978fa5b
proofreading
aloctavodia Dec 20, 2025
2d167dd
proofreading
aloctavodia Dec 22, 2025
50c8c7c
fix trailing whitespace
aloctavodia Dec 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions docs/source/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,11 @@ h3:not(#hero h3) {
<div id="hero-left"> <!-- Start Hero Left -->
<h2 style="font-size: 60px; font-weight: bold; margin: 2rem auto 0;">ArviZ</h2>
<h3 style="font-weight: bold; margin-top: 0;">Exploratory analysis of Bayesian models</h3>
<p>ArviZ is a Python package for exploratory analysis of Bayesian models. It serves as a backend-agnostic tool for diagnosing and visualizing Bayesian inference.</p>
<p>ArviZ is a modular and flexible Python library implementing methods grounded in well-established statistical principles and providing robust, interpretable diagnostics and visualizations for Bayesian workflow.</p>



ArviZ:

<div class="homepage-button-container">
<div class="homepage-button-container-row">
Expand Down Expand Up @@ -152,7 +156,7 @@ Posterior Predictive Check of discrete data using `plot_ppc_rootogram`

:::{div} key-features-text
<strong>Interoperability</strong><br/>
Integrates with all major probabilistic programming libraries: PyMC, CmdStanPy, PyStan, Pyro, NumPyro, and emcee.
Integrates with all major probabilistic programming libraries: PyMC, CmdStanPy, Pyro, NumPyro, and emcee.
:::
::::

Expand All @@ -165,7 +169,7 @@ Integrates with all major probabilistic programming libraries: PyMC, CmdStanPy,

:::{div} key-features-text
<strong>Large Suite of Visualizations</strong><br/>
Provides over 25 plotting functions for all parts of Bayesian workflow: visualizing distributions, diagnostics, and model checking. See the gallery for examples.
Provides over 30 plotting functions for visualizing distributions, MCMC diagnostics, model checking, model comparison. See the gallery for examples.
:::
::::

Expand All @@ -178,7 +182,7 @@ Provides over 25 plotting functions for all parts of Bayesian workflow: visualiz

:::{div} key-features-text
<strong>State of the Art Diagnostics</strong><br/>
Latest published diagnostics and statistics are implemented, tested and distributed with ArviZ.
Modern, theory-grounded diagnostics and statistical tools are implemented, tested and distributed through ArviZ.
:::
::::

Expand All @@ -191,7 +195,7 @@ Latest published diagnostics and statistics are implemented, tested and distribu

:::{div} key-features-text
<strong>Flexible Model Comparison</strong><br/>
Includes functions for comparing models with information criteria, and cross validation (both approximate and brute force).
Includes functions for comparing models using fast approximate cross validation and brute force methods.
:::
::::

Expand Down
25 changes: 14 additions & 11 deletions docs/source/user_guide/getting_started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ kernelspec:
(getting_started)=
# Getting started

## Have you already used <1.0 ArviZ versions?
## Have you used ArviZ versions earlier than 1.0?

We recommend reading the {ref}`migration_guide` instead.

Expand All @@ -23,23 +23,26 @@ We recommend reading the {ref}`migration_guide` instead.
pip install "arviz[<I/O>, <plotting>]"
```

ArviZ is a meta library that pulls together smaller components.
Depending on the libraries you have installed the plotting or I/O functionality
might not be available so we recommend indicating which ones you want to use
whenever you install ArviZ. The options are:
ArviZ brings together several smaller components into one library. Some features, like plotting or reading and writing files, may not be included by default, depending on what you have installed. To make sure you get the features you need, we recommend choosing them when you install ArviZ. You can select from the following options:

* I/O: `zarr`, `netcdf4` and `h5netcdf`
* Plotting: `matplotlib`, `bokeh` and `plotly`

Some example install commands for ArviZ:

For example, if you want to install Zarr and Matplotlib


```{code-block} bash
pip install "arviz[zarr, matplotlib]"
```

If instead you want to use NetCDF and interactive plotting with Plotly and Bokeh then you would run:

```{code-block} bash
pip install "arviz[h5netcdf, plotly, bokeh]"
```

Note you can use any combination of the available options, it is not restricted
to one I/O and one plotting library.
Note that you can mix and match any of the available options. You’re not limited to choosing just one file format or one plotting library.

### Verifying the installation

Expand All @@ -54,9 +57,9 @@ It should look like:
```{code-block} none
Status information for ArviZ 1.0.0

arviz_base 0.7.0 available, exposing its functions as part of the `arviz` namespace
arviz_stats 0.7.0 available, exposing its functions as part of the `arviz` namespace
arviz_plots 0.7.0 available, exposing its functions as part of the `arviz` namespace
arviz_base 1.0.0 available, exposing its functions as part of the `arviz` namespace
arviz_stats 1.0.0 available, exposing its functions as part of the `arviz` namespace
arviz_plots 1.0.0 available, exposing its functions as part of the `arviz` namespace
```

If any of the 3 libraries is missing or can't be imported, the first step for troubleshooting
Expand Down
62 changes: 36 additions & 26 deletions docs/source/user_guide/migration_guide.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,13 @@
"* [arviz-stats](https://arviz-stats.readthedocs.io/en/latest/) for statistical functions and diagnostics.\n",
"* [arviz-plots](https://arviz-plots.readthedocs.io/en/latest/) for visual checks built on top of arviz-stats and arviz-base.\n",
"\n",
"Each library depends only on a minimal set of libraries, with a lot of functionality built on top of optional dependencies.\n",
"Each library has a minimal set of dependencies, with a lot of functionality built on top of optional dependencies.\n",
"This keeps ArviZ smaller and easier to install as you can install only the components you really need. The main examples are:\n",
"\n",
"* `arviz-base` has no I/O library as a dependency, but you can use `netcdf4`, `h5netcdf` or `zarr` to read and write your data, allowing you to install only the one you need.\n",
"* `arviz-plots` has no plotting library as a dependency, but it can generate plots with `matplotlib`, `bokeh` or `plotly` if they are installed.\n",
"\n",
"At the time of writing, `arviz-xyz` libraries are independent of the `arviz` library, but `arviz` tries to import the `arviz-xyz` libraries\n",
"and exposes all their elements through the `arviz.preview` namespace. In the future, with the ArviZ 1.0 release, the `arviz` namespace will look\n",
"At the time of writing, `arviz-xyz` libraries are independent of the `arviz` library, but `arviz` tries to import the `arviz-xyz` libraries and exposes all their elements through the `arviz.preview` namespace. In the future, with the ArviZ 1.0 release, the `arviz` namespace will look\n",
"like `arviz.preview` looks like today.\n",
"\n",
":::{info}\n",
Expand Down Expand Up @@ -91,14 +90,15 @@
"source": [
"### Credible intervals and rcParams\n",
"\n",
"Some global configuration settings have changed. For example, the default credible interval probability (`ci_prob`) has been updated from 0.94 to 0.89. Using 0.89 produces intervals with lower variability, leading to more stable summaries. At the same time, keeping a non-standard value (rather than 0.90 or 0.95) serves as a friendly reminder that the choice of interval should reflect the problem at hand.\n",
"Some global configuration settings have changed. For example, the default credible interval probability (`ci_prob`) has been updated from 0.94 to 0.89. Using 0.89 produces intervals with lower variability, leading to more stable summaries. At the same time, keeping a non-standard value (rather than 0.90 or 0.95) serves as a friendly reminder that the choice of interval can depend on the problem at hand.\n",
"\n",
"In addition, a new setting `ci_kind` has been introduced, which defaults to \"eti\" (equal-tailed interval). This controls the method used to compute credible intervals. The alternative is \"hdi\" (highest density interval), which was previously the default.\n",
"\n",
"\n",
"Defaults set via `rcParams` are not fixed rules, they’re meant to be adjusted to fit the needs of your analysis. `rcParams` offers a convenient way to establish global defaults for your workflow, while most functions that compute credible intervals also provide `ci_prob` and `ci_kind` arguments to override these settings locally.\n",
"\n",
"\n",
"You can check all defatult settings with:"
"You can check all default settings with:"
]
},
{
Expand Down Expand Up @@ -141,7 +141,7 @@
"metadata": {},
"source": [
"### `DataTree`\n",
"One of the main differences is the `arviz.InferenceData` object doesn't exist any more.\n",
"One of the main differences is that the `arviz.InferenceData` object doesn't exist anymore.\n",
"`arviz-base` uses `xarray.DataTree` instead. This is a new data structure in xarray,\n",
"so it might still have some rough edges, but it is much more flexible and powerful.\n",
"To give some examples, I/O will now be more flexible, and any format supported by\n",
Expand All @@ -153,7 +153,7 @@
"work for us to cover and maintain. If there are things you have always wanted to do but\n",
"were not possible with `InferenceData` and are now possible with `DataTree` please try\n",
"them out, give feedback on them and on desired behaviour for things that still don't work.\n",
"After a couple releases the \"ArviZverse\" will stabilize much more and it might not be\n",
"After a couple releases the \"ArviZverse\" will stabilize much more, and it might not be\n",
"possible to add support for that anymore.\n",
":::\n",
"\n",
Expand Down Expand Up @@ -6808,15 +6808,21 @@
"source": [
"#### Other key differences\n",
"`DataTree` supports an arbitrary level of nesting (as opposed to the exactly 1 level of nesting in\n",
"`InferenceData`). Thus, to keep things consistent accessing its groups returns a `DataTree`,\n",
"even if it is a leaf group. This means that `dt[\"posterior\"]` will now return a `DataTree`.\n",
"`InferenceData`). To stay consistent, accessing a groups always returns a `DataTree`,\n",
"even when that group is a leaf. This means that `dt[\"posterior\"]` will now return a `DataTree`.\n",
"In many cases this is irrelevant, but there will be some cases where you'll want the\n",
"group as a `Dataset` instead. You can achieve this with `dt[\"posterior\"].dataset`.\n",
"\n",
"There are no changes at the variable/`DataArray` level. Thus, `dt[\"posterior\"][\"theta\"]` is still\n",
"a `DataArray`, accessing its variables is one of the cases where having either `DataTree`\n",
"or `Dataset` is irrelevant.\n",
"\n",
"or `Dataset` is irrelevant."
]
},
{
"cell_type": "markdown",
"id": "eb0c6f1f",
"metadata": {},
"source": [
"### Enhanced converter flexibility\n",
"Were you constantly needing to add an extra axis to your data because it didn't have any `chain` dimension? No more!"
]
Expand Down Expand Up @@ -8128,10 +8134,11 @@
"PSIS-LOO-CV is more robust, has better theoretical properties, and offers diagnostics\n",
"to assess the reliability of the estimates. For these reasons, we have decided to remove WAIC\n",
"from `arviz-stats`, and instead focus exclusively on PSIS-LOO-CV for model comparison.\n",
"Thus, now we offer many new features related to LOO. Including:\n",
"We now we offer many new features related to PSIS-LOO-CV. Including:\n",
"- Compute weighted expectations, including mean, variance, quantiles, etc. See {func}`~arviz_stats.loo_expectations`.\n",
"- Compute predictive metrics such as RMSE, MAE, etc. See {func}`~arviz_stats.loo_metrics`.\n",
"- Compute CRPS/SCRPS, see {func}`~arviz_stats.loo_score`\n",
"- Compute LOO-R2, see {func}`~arviz_stats.loo_r2`.\n",
"- Compute CRPS/SCRPS, see {func}`~arviz_stats.loo_score`.\n",
"- Compute PSIS-LOO-CV for approximate posteriors. See {func}`~arviz_stats.loo_approximate_posterior`.\n",
"\n",
"\n",
Expand Down Expand Up @@ -9217,13 +9224,10 @@
"When we restrict the target variables to only \"theta\" and \"theta_t\" we make it so\n",
"all variables have both \"school\" and \"draw\" dimension.\n",
"\n",
"All computations where it is required that input variables all have the full set of\n",
"dimensions we want to operate on use `sample_dims`. On ArviZ's side this includes\n",
"`ess`, `rhat` or `mcse`. Xarray only has an example of this:\n",
"{meth}`~xarray.Dataset.to_stacked_array`.\n",
"Whenever a computation requires all input variables to share the same set of dimensions, it uses`sample_dims`.\n",
"On ArviZ's side this includes `ess`, `rhat` or `mcse`. Xarray only has an example of this: {meth}`~xarray.Dataset.to_stacked_array`.\n",
"\n",
"On the other hand, `hdi` uses `dim`. This means that both values we attempted\n",
"for `sample_dims` with `ess` are valid without caveats:"
"On the other hand, `hdi` uses `dim`. This means that both examples we attempted for `ess` and `sample_dims` will work without caveats:"
]
},
{
Expand Down Expand Up @@ -10248,12 +10252,17 @@
"have both \"draw\" and \"school\" reduced. Consequently, all variables end up with \n",
"(\"chain\", \"ci_bound\") dimensions.\n",
"\n",
"All computations where operating over different subsets of the provided dimensions makes\n",
"sense use `dim`. On ArviZ's side this includes functions like `hdi`, `eti` or `kde`.\n",
"Most xarray functions fall in this category too, some examples are {meth}`~xarray.Dataset.mean`,\n",
"{meth}`~xarray.Dataset.quantile`, {meth}`~xarray.Dataset.std` or {meth}`~xarray.Dataset.cumsum`.\n",
"\n",
"Computations that can operate over different subsets of the given dimensions use `dim`.\n",
"On ArviZ's side this includes functions like `hdi`, `eti` or `kde`. Most xarray functions fall in this category too, some examples are {meth}`~xarray.Dataset.mean`, {meth}`~xarray.Dataset.quantile`, {meth}`~xarray.Dataset.std` or {meth}`~xarray.Dataset.cumsum`."
]
},
{
"cell_type": "markdown",
"id": "29a96aab",
"metadata": {},
"source": [
"### Accessors on xarray objects\n",
"\n",
"We are also taking advantage of the fact that xarray allows third party libraries to register\n",
"accessors on its object. This means that _after importing `arviz_stats`_ (or a library that imports\n",
"it like `arviz.preview`) DataArrays, Datasets and DataTrees get a new attribute, `azstats`.\n",
Expand Down Expand Up @@ -10764,6 +10773,7 @@
"metadata": {},
"source": [
"### Computational backends\n",
"\n",
"We have also modified a bit how computations accelerated by optional dependencies are handled.\n",
"There are no longer dedicated \"flag classes\" like we had for Numba and Dask. Instead,\n",
"low level stats functions are implemented in classes so we can subclass and reimplement only\n",
Expand Down Expand Up @@ -14990,7 +15000,7 @@
},
{
"cell_type": "code",
"execution_count": 24,
"execution_count": null,
"id": "a862f196-0315-4d55-baf3-9e76fd86df8d",
"metadata": {
"lines_to_next_cell": 0
Expand Down Expand Up @@ -15027,7 +15037,7 @@
" ],\n",
" var_names=[\"theta\", \"mu\", \"tau\"],\n",
" coords={\"school\": [\"Hotchkiss\", \"St. Paul's\"]},\n",
")"
");"
]
},
{
Expand Down
Loading