Arviz: Make namespace flat

[ColCarroll]

Plan is to have a flat namespace for public functions:

• plot_ (plot_forest, plot_autocorrelation, etc)
• stat_ (not wild about this naming convention - maybe just make sure these names are descriptive and exposed in the top-level namespace. thoughts?)
• other functions (convert_to_xarray, style.use)
• Rename load_arviz_data to load_dataset
• Make sure libraries like matplotlib.pyplot or xarray are not making it into the arviz namespace.

[canyon289]

To me it depends on how large this library is going to get.
If its mostly just plotting and plotting utils then I like seaborns approach which is similar to the current api
https://seaborn.pydata.org/api.html

If this package is going to have plotting, and a bunch of utility functions and statistics, then scikit learns nested API is the opposite extreme.

Right now it seems like this package is in the middle, with mostly plotting, but some other functionality built in as well.

If we think people are mostly going to use this package for statistics, perhaps leave those in the top level namespace, and then put stats, utils, diagnostics into its own?

For for example
az.traceplot or az.plot_trace

and for stats
az.stats.summary

Same for utils
az.utils.convert_to_xarray

[ahartikainen]

Hi,

I'm not sure if convert_to_xarray, convert_to_dataset or convert_to_inference_data are best names.

I usually first try from_ and I don't find anything, I try read_ or to_

We could have

az.from_numpy
az.from_stan
az.from_pymc3
az.from_dict

or maybe

az.to_arviz az.to_dataset # az.to_xarray ?

which would return either arviz.inference_data and xarray_dataset.

[ColCarroll]

My only hesitation with that is that there will be different return types (turning a numpy array into inference data is a _ton_ of guessing about intentions). What about exposing

to_inference_data
to_dataset
from_pymc3
from_stan

in the top level, and rename the directory to convert, so you can az.convert.dict_to_dataset or az.convert.numpy_to_dataarray if you need extra specificity.

I know it is not consistent, but I sort of like that from_pymc3 accepts a trace argument, while from_stan accepts a fit object, which will be familiar to users of the library. Hopefully from_pyro and from_tfp will show up soon!

[MFreidank]

Sorry for asking stupid questions, I was quite busy at work lately and could not follow the discussions as closely as I would have liked. Is the idea mainly to republish things that are currently in submodules in the main namespace, as in:

# arviz/__init__.py 
from arviz.plots.forestplot import plot_forest

or is this about actually moving the submodules into toplevel namespace?

[ColCarroll]

It has ended up being a little bit of both!

• Submodules were actually renamed and rearranged, mostly getting rid of utils.py and xarray_utils.py, whose functions are now in the data directory
• The plots directory still exists, and the files have the same names, but the plot function names are all changed (I think this is what you meant by republish)

The output of tree is below, in case that's helpful.

 ➜  arviz (master)  tree .
.
├── data
│   ├── base.py
│   ├── converters.py
│   ├── _datasets
│   │   ├── centered_eight.nc
│   │   ├── non_centered_eight.nc
│   │   └── radon.nc
│   ├── inference_data.py
│   ├── __init__.py
│   ├── io_netcdf.py
│   ├── io_pymc3.py
│   └── io_pystan.py
├── __init__.py
├── plots
│   ├── autocorrplot.py
│   ├── compareplot.py
│   ├── densityplot.py
│   ├── energyplot.py
│   ├── forestplot.py
│   ├── __init__.py
│   ├── jointplot.py
│   ├── kdeplot.py
│   ├── khatplot.py
│   ├── pairplot.py
│   ├── parallelplot.py
│   ├── plot_utils.py
│   ├── posteriorplot.py
│   ├── ppcplot.py
│   ├── styles
│   │   ├── arviz-darkgrid.mplstyle
│   │   └── arviz-whitegrid.mplstyle
│   ├── traceplot.py
│   └── violinplot.py
├── stats
│   ├── diagnostics.py
│   ├── __init__.py
│   └── stats.py
└── tests
    ├── helpers.py
    ├── __init__.py
    ├── saved_models
    │   ├── 3.6_pymc3_3.5_500_2.pkl
    │   └── 3.6_pystan_2.18.0.0_500_2.pkl
    ├── test_data.py
    ├── test_diagnostics.py
    ├── test_plots.py
    ├── test_plot_utils.py
    └── test_stats.py

7 directories, 41 files

[ColCarroll]

Marking this as done, by the way.