Skip to content

Commit

Permalink
doc tweaks
Browse files Browse the repository at this point in the history
  • Loading branch information
@OriolAbril
OriolAbril committed Feb 20, 2021
1 parent a12f99e commit 2ab531c
Show file tree
Hide file tree
Showing 4 changed files with 51 additions and 43 deletions.
3 changes: 2 additions & 1 deletion .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@ coverage.xml
*.log

# Sphinx documentation
docs/source/_build/
doc/build/
doc/source/savefig

# PyBuilder
target/
Expand Down
14 changes: 7 additions & 7 deletions arviz/labels.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,8 @@ def mix_labellers(labellers, class_name="MixtureLabeller"):
Examples
--------
Combine the :class:`~arviz.labels.DimCoordLabeller`` with the
:class:`~arviz.labels.MapLabeller`` to generate labels in the style of the
Combine the :class:`~arviz.labels.DimCoordLabeller` with the
:class:`~arviz.labels.MapLabeller` to generate labels in the style of the
``DimCoordLabeller`` but using the mappings defined by ``MapLabeller``.
Note that this works even though both modify the same methods because
``MapLabeller`` implements the mapping and then calls `super().method`.
Expand All @@ -59,12 +59,12 @@ def mix_labellers(labellers, class_name="MixtureLabeller"):
We can see how the mappings are taken into account as well as the dim+coord style. However,
he order in the ``labellers`` arg iterator is important! See for yourself:
.. ipython::
.. ipython:: python
In [1]: l4 = mix_labellers(
...: (DimCoordLabeller, MapLabeller)
...: )(dim_map={"dim1": "$d_1$", "dim2": r"$d_2$"})
...: print(f"Output of inverted mixture labeller > {l4.sel_to_str(sel, sel)}")
l4 = mix_labellers(
(DimCoordLabeller, MapLabeller)
)(dim_map={"dim1": "$d_1$", "dim2": r"$d_2$"})
print(f"Output of inverted mixture labeller > {l4.sel_to_str(sel, sel)}")
"""
return type(class_name, labellers, {})
Expand Down
2 changes: 1 addition & 1 deletion doc/source/api/plot_utils.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

(labeller_api)=
## Labellers
See also `<upcoming user guide page on labellers>`
See also the {ref}`label_guide`

```{eval-rst}
.. autosummary::
Expand Down
75 changes: 41 additions & 34 deletions doc/source/user_guide/label_guide.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,10 @@ Provided we know that the coordinate values shown for theta correspond to the `s
we can plot only ``tau`` to better inspect it's 1.03 :func:`~arviz.rhat` and
``theta`` for ``Choate`` and ``St. Paul's``, the ones with higher means:

.. ipython::
.. ipython:: python
In [1]: az.plot_trace(schools, var_names=["tau", "theta"], coords={"school": ["Choate", "St. Paul's"]}, compact=False);
@savefig label_guide_plot_trace.png
az.plot_trace(schools, var_names=["tau", "theta"], coords={"school": ["Choate", "St. Paul's"]}, compact=False);
So far so good, we can identify some issues for low ``tau`` values which is great start.
But say we want to make a report on Deerfield, Hotchkiss and Lawrenceville schools to
Expand All @@ -45,7 +46,9 @@ tell it to rename the variable name ``theta`` to ``$\theta$``, like so:
In [1]: import arviz.labels as azl
...: labeller = azl.MapLabeller(var_name_map={"theta": r"$\theta$"})
...: coords = {"school": ["Deerfield", "Hotchkiss", "Lawrenceville"]}
...: az.plot_posterior(schools, var_names="theta", coords=coords, labeller=labeller, ref_val=5);

@savefig label_guide_plot_posterior.png
In [1]: az.plot_posterior(schools, var_names="theta", coords=coords, labeller=labeller, ref_val=5);

You can see the labellers available in ArviZ at :ref:`their API reference page <labeller_api>`.
Their names aim to be descriptive and they all have examples in their docstring.
Expand Down Expand Up @@ -165,18 +168,18 @@ Given how we have constructed our dataset, the default order is ``experiment, su
Hovever, we actually want to have the dimensions in this order: ``subject, date, experiment``.
And in this case, we need to modify the underlying xarray object in order to get the desired result:

.. ipython::
.. ipython:: python
In [1]: dim_order = ("chain", "draw", "subject", "date", "experiment")
...: experiments = experiments.posterior.transpose(*dim_order)
...: az.summary(experiments)
dim_order = ("chain", "draw", "subject", "date", "experiment")
experiments = experiments.posterior.transpose(*dim_order)
az.summary(experiments)
Note however that we don't need to overwrite or store the modified xarray object.
Doing ``az.summary(experiments.posterior.transpose(*dim_order))`` would work just the same
if we only want to use this order once.

Labeling with indexes
=====================
---------------------

As you may have seen, there are labellers with ``Idx`` in their name:
:class:`~arviz.labels.IdxLabeller` and :class:`~arviz.labels.DimIdxLabeller`,
Expand All @@ -186,15 +189,15 @@ We have seen before that we can use the ``coords`` argument or
the :meth:`~arviz.InferenceData.sel` method to select data based on the coordinate values.
Similarly, we can use the :meth:`~arviz.InferenceData.isel` method to select data based on positional indexes.

.. ipython::
.. ipython:: python
In [1]: az.summary(schools, labeller=azl.IdxLabeller())
az.summary(schools, labeller=azl.IdxLabeller())
After seeing this summary, we use ``isel`` to generate the summary of a subset only.

.. ipython::
.. ipython:: python
In [1]: az.summary(schools.isel(school=[2, 5, 7]), labeller=azl.IdxLabeller())
az.summary(schools.isel(school=[2, 5, 7]), labeller=azl.IdxLabeller())
.. warning::

Expand All @@ -211,7 +214,7 @@ for ``isel`` to work it has to be called on
not on ``original_idata.isel(<desired positional idxs>)``

Labeller mixtures
=================
-----------------

In some cases, none of the available labellers will do the right job.
One case where this is bound to happen is with ``plot_forest``.
Expand All @@ -220,17 +223,19 @@ When setting ``legend=True`` it does not really make sense to add the model name
:class:`~arviz.labels.BaseLabeller` or :class:`~arviz.labels.NoModelLabeller` depending on the value of ``legend``.
If we do want to use the ``labeller`` argument however, we have to make sure to enforce this default ourselves:

.. ipython::
.. ipython:: python
schools2 = az.load_arviz_data("non_centered_eight")
In [1]: schools2 = az.load_arviz_data("non_centered_eight")
...: az.plot_forest(
...: (schools, schools2),
...: model_names=("centered", "non_centered"),
...: coords={"school": ["Deerfield", "Lawrenceville", "Mt. Hermon"]},
...: figsize=(10,7),
...: labeller=azl.DimCoordLabeller(),
...: legend=True
...: );
@savefig default_plot_forest.png
az.plot_forest(
(schools, schools2),
model_names=("centered", "non_centered"),
coords={"school": ["Deerfield", "Lawrenceville", "Mt. Hermon"]},
figsize=(10,7),
labeller=azl.DimCoordLabeller(),
legend=True
);
There is a lot of repeated information now.
The variable names, dims and coords are shown for both models and
Expand All @@ -240,19 +245,21 @@ that combines labeller classes for some extra customization.
Labeller classes aim to split labeling into atomic tasks and have a method per task to maximize extensibility.
Thus, many new labellers can be created with this mixer function alone without needing to write a new class from scratch.

.. ipython::
.. ipython:: python
MixtureLabeller = azl.mix_labellers((azl.DimCoordLabeller, azl.NoModelLabeller))
In [1]: MixtureLabeller = azl.mix_labellers((azl.DimCoordLabeller, azl.NoModelLabeller))
...: az.plot_forest(
...: (schools, schools2),
...: model_names=("centered", "non_centered"),
...: coords={"school": ["Deerfield", "Lawrenceville", "Mt. Hermon"]},
...: figsize=(10,7),
...: labeller=MixtureLabeller(),
...: legend=True
...: );
@savefig mixture_plot_forest.png
az.plot_forest(
(schools, schools2),
model_names=("centered", "non_centered"),
coords={"school": ["Deerfield", "Lawrenceville", "Mt. Hermon"]},
figsize=(10,7),
labeller=MixtureLabeller(),
legend=True
);
Custom labellers
================
----------------

Section in construction...

0 comments on commit 2ab531c

Please sign in to comment.