DeprecationWarning: removing deprecated methods

[Jocho-Smith]

This issue addresses 2 things:

1. prepare the upcoming deprecation warnings convention for the GSoC projects of @Jocho-Smith and @satwiksps - so we know how and when to introduce deprecation warnings.
2. initiate documentation for deprecation warning in general for sbi.

1. GSoC

@dgedon suggested today that Satwik and I should not necessarily be part of the general deprecation process. It is enough if we all just make sure, that if we deprecate methods, this should only be merged 'consciously' after the new proposed workflow is functioning correctly. This will likely not be the next release, but the one after that (and after GSoC).

In terms of the actual code, I propose to just do it the way the other warnings were written so far:

warnings.warn(
    "This function is deprecated and will be removed in a future release. Use "
    "`XYZ` instead.",
    DeprecationWarning,
    stacklevel=2,
)

2. deprecation in general

I think deleting deprecated methods can happen in 2 ways: Gradually with smaller releases once they have been deprecated for a long time or all together after a major release. Both could be applied here, knowing that no major release updates are planed yet- still it might be useful to keep the deprecated things in mind for that release in the future.

Here is an example of an older deprecated method: MixedLikelihoodBasedPotential. Git blame revealed that this is deprecated now for 2 years.

Running git grep -rin DeprecationWarning reveals all deprecated functions:

sbi/analysis/plot.py:1028:        DeprecationWarning,
sbi/analysis/plot.py:2562:        PendingDeprecationWarning,
sbi/analysis/plot.py:2632:        PendingDeprecationWarning,
sbi/analysis/plot.py:2864:        PendingDeprecationWarning,
sbi/diagnostics/sbc.py:78:            DeprecationWarning,
sbi/inference/posteriors/mcmc_posterior.py:116:                DeprecationWarning,
sbi/inference/posteriors/mcmc_posterior.py:940:                    DeprecationWarning,
sbi/inference/potentials/likelihood_based_potential.py:155:            DeprecationWarning,
sbi/inference/potentials/likelihood_based_potential.py:420:        DeprecationWarning,
sbi/inference/potentials/likelihood_based_potential.py:447:            DeprecationWarning,
sbi/inference/potentials/posterior_based_potential.py:183:            DeprecationWarning,
sbi/inference/potentials/ratio_based_potential.py:134:            DeprecationWarning,
sbi/utils/posterior_ensemble.py:16:warnings.filterwarnings("default", category=DeprecationWarning, module=__name__)
sbi/utils/posterior_ensemble.py:24:    DeprecationWarning,
sbi/utils/posterior_ensemble.py:38:        DeprecationWarning,
sbi/utils/posterior_ensemble.py:54:        DeprecationWarning,
sbi/utils/user_input_checks.py:668:        DeprecationWarning,
tests/ensemble_test.py:24:    with pytest.warns(DeprecationWarning):

This issue can be a starting point for the creation of a removal plan of deprecated methods. I hope this helps :)

[janfb]

Awesome, thanks @Jocho-Smith 🙏

[dgedon]

Thanks @Jocho-Smith! I would say both @satwiksps and you can follow the general procedure of deprecations. For now we would want to have clear deprecation warnings if something happens. But we also need a documentation about what is deprecated, what it affects, since when it is deprecated and a plan how/when to remove it from the codebase. This general procedure is WIP.