return_inferencedata option for pm.sample (#3911)

* mention arviz functions by name in warning

* convert to InferenceData already in sample function
+ convert to InferenceData and save metadata to it already in sample()
+ pass idata instead of trace to convergence check, to avoid duplicate work
+ directly use arviz diagnostics instead of pymc3 aliases

* fix refactoring bugs

* fix indentation

* add return_inferencedata option
+ set to None
+ defaults to False

* Fix numpy docstring format.

Replaced "<varname>: <type>" with "<varname> : <type>" per numpy guidelines.

Fix spelling typo.

* pass model to from_pymc3 because of deprecation warning

* add test for return_inferencedata option

* advise against keeping warmup draws in a MultiTrace

* mention #3911

* pin to arviz 0.8.0 and address review feedback

* rerun/update notebook to show inferencedata trace

* fix typo

* make all from_pymc3 accessible to the user

* remove duplicate entry, and wording

* address review feedback

* update arviz to 0.8.1 because of bugfix

* incorporate review feedback
+ more direct use of ArviZ
+ some wording things

* use arviz plot_ppc

* also ignore Visual Studio cache

* fix warmup saving logic and test

* require latest ArviZ patch

* change warning to nuget users towards InferenceData

* update ArviZ minimum version

* address review feedback

* start showing the FutureWarning about return_inferencedata in minor release >=3.10

* require arviz>=0.8.3 for latest bugfix

Co-authored-by: rpgoldman <[email protected]>

Author: michaelosthege

.gitignore

@@ -33,7 +33,8 @@ benchmarks/html/
 benchmarks/results/
 .pytest_cache/
 
-# VSCode
+# Visual Studio / VSCode
+.vs/
 .vscode/
 .mypy_cache
 

RELEASE-NOTES.md

@@ -11,6 +11,7 @@
 - GP covariance functions can now be exponentiated by a scalar. See PR [#3852](https://github.com/pymc-devs/pymc3/pull/3852)
 - `sample_posterior_predictive` can now feed on `xarray.Dataset` - e.g. from `InferenceData.posterior`. (see [#3846](https://github.com/pymc-devs/pymc3/pull/3846))
 - `SamplerReport` (`MultiTrace.report`) now has properties `n_tune`, `n_draws`, `t_sampling` for increased convenience (see [#3827](https://github.com/pymc-devs/pymc3/pull/3827))
+- `pm.sample(..., return_inferencedata=True)` can now directly return the trace as `arviz.InferenceData` (see [#3911](https://github.com/pymc-devs/pymc3/pull/3911))
 - `pm.sample` now has support for adapting dense mass matrix using `QuadPotentialFullAdapt` (see [#3596](https://github.com/pymc-devs/pymc3/pull/3596), [#3705](https://github.com/pymc-devs/pymc3/pull/3705), [#3858](https://github.com/pymc-devs/pymc3/pull/3858), and [#3893](https://github.com/pymc-devs/pymc3/pull/3893)). Use `init="adapt_full"` or `init="jitter+adapt_full"` to use.
 - `Moyal` distribution added (see [#3870](https://github.com/pymc-devs/pymc3/pull/3870)).
 - `pm.LKJCholeskyCov` now automatically computes and returns the unpacked Cholesky decomposition, the correlations and the standard deviations of the covariance matrix (see [#3881](https://github.com/pymc-devs/pymc3/pull/3881)).
@@ -21,6 +22,8 @@
 
 ### Maintenance
 - Tuning results no longer leak into sequentially sampled `Metropolis` chains (see #3733 and #3796).
+- We'll deprecate the `Text` and `SQLite` backends and the `save_trace`/`load_trace` functions, since this is now done with ArviZ. (see [#3902](https://github.com/pymc-devs/pymc3/pull/3902))
+- ArviZ `v0.8.3` is now the minimum required version
 - In named models, `pm.Data` objects now get model-relative names (see [#3843](https://github.com/pymc-devs/pymc3/pull/3843)).
 - `pm.sample` now takes 1000 draws and 1000 tuning samples by default, instead of 500 previously (see [#3855](https://github.com/pymc-devs/pymc3/pull/3855)).
 - Moved argument division out of `NegativeBinomial` `random` method. Fixes [#3864](https://github.com/pymc-devs/pymc3/issues/3864) in the style of [#3509](https://github.com/pymc-devs/pymc3/pull/3509).
@@ -34,7 +37,7 @@
 
 ### Deprecations
 - Remove `sample_ppc` and `sample_ppc_w` that were deprecated in 3.6.
-- Deprecated `sd` in version 3.7 has been replaced by `sigma` now raises `DeprecationWarning` on using `sd` in continuous, mixed and timeseries distributions. (see [#3837](https://github.com/pymc-devs/pymc3/pull/3837) and [#3688](https://github.com/pymc-devs/pymc3/issues/3688)).
+- Deprecated `sd` has been replaced by `sigma` (already in version 3.7) in continuous, mixed and timeseries distributions and now raises `DeprecationWarning` when `sd` is used. (see [#3837](https://github.com/pymc-devs/pymc3/pull/3837) and [#3688](https://github.com/pymc-devs/pymc3/issues/3688)).
 - We'll deprecate the `Text` and `SQLite` backends and the `save_trace`/`load_trace` functions, since this is now done with ArviZ. (see [#3902](https://github.com/pymc-devs/pymc3/pull/3902))
 - Dropped some deprecated kwargs and functions (see [#3906](https://github.com/pymc-devs/pymc3/pull/3906))
 - Dropped the outdated 'nuts' initialization method for `pm.sample` (see [#3863](https://github.com/pymc-devs/pymc3/pull/3863)).