v4.0.0b1

PyMC 4.0.0 beta 1

⚠ This is the first beta of the next major release for PyMC 4.0.0 (formerly PyMC3). 4.0.0 is a rewrite of large parts of the PyMC code base which make it faster, adds many new features, and introduces some breaking changes. For the most part, the API remains stable and we expect that most models will work without any changes.

Not-yet working features

We plan to get these working again, but at this point, their inner workings have not been refactored.

• Timeseries distributions (see #4642)
• Mixture distributions (see #4781)
• Cholesky distributions (see WIP PR #4784)
• Variational inference submodule (see WIP PR #4582)
• Elliptical slice sampling (see #5137)
• BaseStochasticGradient (see #5138)
• pm.sample_posterior_predictive_w (see #4807)
• Partially observed Multivariate distributions (see #5260)

Also, check out the milestones for a potentially more complete list.

Unexpected breaking changes (action needed)

• New API is not available in v3.11.5.
• Old API does not work in v4.0.0.

All of the above applies to:

• ⚠ The library is now named, installed, and imported as "pymc". For example: pip install pymc. (Use pip install pymc --pre while we are in the pre-release phase.)
• ⚠ Theano-PyMC has been replaced with Aesara, so all external references to theano, tt, and pymc3.theanof need to be replaced with aesara, at, and pymc.aesaraf (see 4471).
• pm.Distribution(...).logp(x) is now pm.logp(pm.Distribution(...), x)
• pm.Distribution(...).logcdf(x) is now pm.logcdf(pm.Distribution(...), x)
• pm.Distribution(...).random() is now pm.Distribution(...).eval()
• pm.draw_values(...) and pm.generate_samples(...) were removed. The tensors can now be evaluated with .eval().
• pm.fast_sample_posterior_predictive was removed.
• pm.sample_prior_predictive, pm.sample_posterior_predictive and pm.sample_posterior_predictive_w now return an InferenceData object by default, instead of a dictionary (see #5073).
• pm.sample_prior_predictive no longer returns transformed variable values by default. Pass them by name in var_names if you want to obtain these draws (see 4769).
• pm.sample(trace=...) no longer accepts MultiTrace or len(.) > 0 traces (see 5019#).
• The GLM submodule was removed, please use Bambi instead.
• pm.Bound interface no longer accepts a callable class as an argument, instead, it requires an instantiated distribution (created via the .dist() API) to be passed as an argument. In addition, Bound no longer returns a class instance but works as a normal PyMC distribution. Finally, it is no longer possible to do predictive random sampling from Bounded variables. Please, consult the new documentation for details on how to use Bounded variables (see 4815).
• pm.logpt(transformed=...) kwarg was removed (816b5f).
• Model(model=...) kwarg was removed
• Model(theano_config=...) kwarg was removed
• Model.size property was removed (use Model.ndim instead).
• dims and coords handling:
  • Model.RV_dims and Model.coords are now read-only properties. To modify the coords dictionary use Model.add_coord.
  • dims or coordinate values that are None will be auto-completed (see #4625).
  • Coordinate values passed to Model.add_coord are always converted to tuples (see #5061).
• Model.update_start_values(...) was removed. Initial values can be set in the Model.initial_values dictionary directly.
• Test values can no longer be set through pm.Distribution(testval=...) and must be assigned manually.
• Transform.forward and Transform.backward signatures changed.
• pm.DensityDist no longer accepts the logp as its first positional argument. It is now an optional keyword argument. If you pass a callable as the first positional argument, a TypeError will be raised (see 5026).
• pm.DensityDist now accepts distribution parameters as positional arguments. Passing them as a dictionary in the observed keyword argument is no longer supported and will raise an error (see 5026).
• The signature of the logp and random functions that can be passed into a pm.DensityDist has been changed (see 5026).
• Changes to the Gaussian process (gp) submodule:
  • The gp.prior(..., shape=...) kwarg was renamed to size.
  • Multiple methods including gp.prior now require explicit kwargs.
• Changes to the BART implementation:
  • A BART variable can be combined with other random variables. The inv_link argument has been removed (see 4914).
  • Moved BART to its own module (see 5058).
• Changes to the Gaussian Process (GP) submodule (see 5055):
  • For all implementations, gp.Latent, gp.Marginal etc., cov_func and mean_func are required kwargs.
  • In Windows test conda environment the mkl version is fixed to verison 2020.4, and mkl-service is fixed to 2.3.0. This was required for gp.MarginalKron to function properly.
  • gp.MvStudentT uses rotated samples from StudentT directly now, instead of sampling from pm.Chi2 and then from pm.Normal.
  • The "jitter" parameter, or the diagonal noise term added to Gram matrices such that the Cholesky is numerically stable, is now exposed to the user instead of hard-coded. See the function gp.util.stabilize.
  • The is_observed argument for gp.Marginal* implementations has been deprecated.
  • In the gp.utils file, the kmeans_inducing_points function now passes through kmeans_kwargs to scipy's k-means function.
  • The function replace_with_values function has been added to gp.utils.
  • MarginalSparse has been renamed MarginalApprox.

Expected breaks

• New API was already available in v3.
• Old API had deprecation warnings since at least 3.11.0 (2021-01).
• Old API stops working in v4 (preferably with informative errors).

All of the above apply to:

• pm.sample(return_inferencedata=True) is now the default (see #4744).
• ArviZ plots and stats wrappers were removed. The functions are now just available by their original names (see #4549 and 3.11.2 release notes).
• pm.sample_posterior_predictive(vars=...) kwarg was removed in favor of var_names (see #4343).
• ElemwiseCategorical step method was removed (see #4701)

Ongoing deprecations

• Old API still works in v4 and has a deprecation warning.
• Preferably the new API should be available in v3 already

New features

• The length of dims in the model is now tracked symbolically through Model.dim_lengths (see #4625).
• The CAR distribution has been added to allow for use of conditional autoregressions which often are used in spatial and network models.
• The dimensionality of model variables can now be parametrized through either of shape, dims or size (see #4696):
  • With shape the length of dimensions must be given numerically or as scalar Aesara Variables. Numeric entries in shape restrict the model variable to the exact length and re-sizing is no longer possible.
  • dims keeps model variables re-sizeable (for example through pm.Data) and leads to well-defined coordinates in InferenceData objects.
  • The size kwarg behaves as it does in Aesara/NumPy. For univariate RVs it is the same as shape, but for multivariate RVs it depends on how the RV implements broadcasting to dimensionality greater than RVOp.ndim_supp.
  • An Ellipsis (...) in the last position of shape or dims can be used as shorthand notation for implied dimensions.
• Added a logcdf implementation for the Kumaraswamy distribution (see #4706).
• The OrderedMultinomial distribution has been added for use on ordinal data which are aggregated by trial, like multinomial observations, whereas OrderedLogistic only accepts ordinal data in a disaggregated format, like categorical
  observations (see #4773).
• The Polya-Gamma distribution has been added (see #4531). To make use of this distribution, the polyagamma>=1.3.1 library must be installed and available in the user's environment.
• A small change to the mass matrix tuning methods jitter+adapt_diag (the default) and adapt_diag improves performance early on during tuning for some models. #5004
• New experimental mass matrix tuning method jitter+adapt_diag_grad. #5004
• pm.DensityDist can now accept an optional logcdf keyword argument to pass in a function to compute the cummulative density function of the distribution (see 5026).
• pm.DensityDist can now accept an optional get_moment keyword argument to pass in a function to compute the moment of the distribution (see 5026).
• New features for BART:
  • Added partial dependence plots and individual conditional expectation plots 5091.
  • Modify how particle weights are computed. This improves the accuracy of the modeled function (see 5177).
  • Improve sampling, increase the default number of particles 5229.
• pm.Data now passes additional kwargs to aesara.shared. #5098
• ...

Internal changes

• ⚠ PyMC now requires Scipy version >= 1.4.1 (see 4857).
• Removed float128 dtype support (see #4514).
• Logp method of Uniform and DiscreteUniform no longer depends on pymc.distributions.dist_math.bound for proper evaluation (see #4541).
• We now include cloudpickle as a required dependency, and no longer depend on dill (see #4858).
• The incomplete_beta function in pymc.distributions.dist_math was replaced by aesara.tensor.betainc (see 4857).
• math.log1mexp and math.log1mexp_numpy will expect negative inputs in the future. A FutureWarning is now raised unless negative_input=True is set (see #4860).
• Changed name of Lognormal distribution to LogNormal to harmonize CamelCase usage for distribution names.
• Attempt to iterate over MultiTrace will raise NotImplementedError.
• ...