MAINT: add sampler deprecation warning (#822)

* MAINT: add sampler deprecation warning for pypolychord

* MAINT: add sampler deprecation warning for nessai

* DOC: change important to warning

* DOC: add samplers to sampler plugin library

* DOC: add docs about migrating to sampler plugins

bilby/core/sampler/nessai.py

@@ -1,5 +1,6 @@
 import os
 import sys
+import warnings
 
 import numpy as np
 from pandas import DataFrame
@@ -12,6 +13,11 @@
 class Nessai(NestedSampler):
     """bilby wrapper of nessai (https://github.com/mj-will/nessai)
 
+    .. warning::
+        The nessai sampler interface in bilby is deprecated and will be
+        removed in future release. Please use the :code`nessai-bilby`
+        sampler plugin instead: https://github.com/bilby-dev/nessai-bilby
+
     All positional and keyword arguments passed to `run_sampler` are propagated
     to `nessai.flowsampler.FlowSampler`
 
@@ -25,6 +31,13 @@ class Nessai(NestedSampler):
     _run_kwargs_list = None
     sampling_seed_key = "seed"
 
+    msg = (
+        "The nessai sampler interface in bilby is deprecated and will"
+        " be removed in future release. Please use the `nessai-bilby`"
+        "sampler plugin instead: https://github.com/bilby-dev/nessai-bilby."
+    )
+    warnings.warn(msg, FutureWarning)
+
     @property
     def run_kwargs_list(self):
         """List of kwargs used in the run method of :code:`FlowSampler`"""

bilby/core/sampler/polychord.py

@@ -1,4 +1,5 @@
 import os
+import warnings
 
 import numpy as np
 
@@ -11,6 +12,11 @@ class PyPolyChord(NestedSampler):
     Bilby wrapper of PyPolyChord
     https://arxiv.org/abs/1506.00171
 
+    .. warning::
+        The PyPolyChord sampler interface in bilby is deprecated and will be
+        removed in future release. Please use the :code`pypolychord-bilby`
+        sampler plugin instead: https://github.com/bilby-dev/pypolychord-bilby
+
     PolyChordLite is available at:
     https://github.com/PolyChord/PolyChordLite
 
@@ -22,6 +28,13 @@ class PyPolyChord(NestedSampler):
     To see what the keyword arguments are for, see the docstring of PyPolyChordSettings
     """
 
+    msg = (
+        "The PyPolyChord sampler interface in bilby is deprecated and will"
+        " be removed in future release. Please use the `pypolychord-bilby`"
+        "sampler plugin instead: https://github.com/bilby-dev/pypolychord-bilby."
+    )
+    warnings.warn(msg, FutureWarning)
+
     sampler_name = "pypolychord"
     default_kwargs = dict(
         use_polychord_defaults=False,

docs/plugins.txt

@@ -58,7 +58,8 @@ This is a list of known sampler plugins. if you don't see your plugin listed
 here, we encourage you to open a
 `pull request <https://github.com/bilby-dev/bilby/compare>`_ to add it.
 
-- This could be your sampler
+- :code:`nessai-bilby`: https://github.com/bilby-dev/nessai-bilby
+- :code:`pypolychord-bilby`: https://github.com/bilby-dev/pypolychord-bilby
 
 
 Bilby-native samplers

docs/samplers.txt

@@ -81,7 +81,7 @@ A list of available samplers can be produced using
 :py:func:`bilby.core.sampler.get_implemented_samplers`.
 This will list native bilby samplers and any samplers available via a plugin.
 If a plugin provides a sampler that is also implemented in bilby, the bilby
-implementation will be labeled with the prfix `bilby.` to distinguish it from
+implementation will be labeled with the prefix `bilby.` to distinguish it from
 the plugin version. See `sampler plugins`_ for more details.
 
 
@@ -112,6 +112,11 @@ be found in the at the top-level of `the repository
 <https://github.com/bilby-dev/bilby>`_ (Note: if you installed from pip, you
 can simply download that file and use the command above).
 
+.. note::
+
+   Some samplers are being migrated to use sampler plugins and may require an
+   additional step, see `migrating to sampler plugins`_.
+
 
 Installing PyPolyChord
 ======================
@@ -173,8 +178,30 @@ replacing the path where appropriate)
 Adding new samplers to bilby
 ----------------------------
 
-We actively encourage the addition of new samplers to :code:`bilby`. To help
-enable this, we have base classes which can be subclassed. Below we provide the
-API for reference, note that the :code:`NestedSampler` and :code:`MCMCSampler`
-inherit from the :code:`Sampler` class.
+We actively encourage the addition of new samplers to :code:`bilby`.
+We now recommended adding support for new samplers via the sampler plugins
+interface. For more details, and a template, see `sampler plugins`_.
+
+----------------------------
+Migrating to sampler plugins
+----------------------------
+
+The interfaces for some samplers are being move from bilby to external sampler
+plugins. This does not change how the samplers are used for most users, you
+still specify :code:`sampler='sampler name'` in :code:`run_sampler`, however,
+an additional dependency must be installed before using a sampler.
+
+.. note::
+   Samplers that are scheduled to be moved will print a warning when using them.
+
+For example, the :code:`nessai` sampler interface has been moved to a plugin.
+In order for a user to continue using this sampler, they must install the
+`nessai-bilby` `plugin <https://github.com/bilby-dev/nessai-bilby>`_ which is
+available via PyPI and conda. Once this package is installed, the new interface
+will automatically be used instead of the native bilby interface.
+
+.. warning::
+   Some samplers may require additional installation steps.
 
+For more details about how sampler plugins, including a list of available
+sampler plugins, see `sampler plugins`_.