DEPR: deprecate HaloCatalogCallback, let it migrate to yt_astro_analysis

doc/source/reference/api/api.rst

@@ -681,7 +681,6 @@ See also :ref:`callbacks`.
    ~yt.visualization.plot_modifications.ContourCallback
    ~yt.visualization.plot_modifications.CuttingQuiverCallback
    ~yt.visualization.plot_modifications.GridBoundaryCallback
-   ~yt.visualization.plot_modifications.HaloCatalogCallback
    ~yt.visualization.plot_modifications.ImageLineCallback
    ~yt.visualization.plot_modifications.LinePlotCallback
    ~yt.visualization.plot_modifications.MagFieldCallback

doc/source/visualizing/callbacks.rst

@@ -392,60 +392,6 @@ Overplot Cell Edges
    slc.annotate_cell_edges()
    slc.save()
 
-.. _annotate-halos:
-
-Overplot Halo Annotations
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. function:: annotate_halos(self, halo_catalog, circle_args=None, \
-                             width=None, annotate_field=None, \
-                             radius_field='virial_radius', \
-                             center_field_prefix="particle_position", \
-                             text_args=None, factor=1.0)
-
-   (This is a proxy for
-   :class:`~yt.visualization.plot_modifications.HaloCatalogCallback`.)
-
-   Accepts a :class:`~yt_astro_analysis.halo_analysis.halo_catalog.HaloCatalog`
-   and plots a circle at the location of each halo with the radius of the
-   circle corresponding to the virial radius of the halo. Also accepts a
-   :ref:`loaded halo catalog dataset <halo-catalog-data>` or a data
-   container from a halo catalog dataset. If ``width`` is set
-   to None (default) all halos are plotted, otherwise it accepts a tuple in
-   the form (1.0, ‘Mpc’) to only display halos that fall within a slab with
-   width ``width`` centered on the center of the plot data.  The appearance of
-   the circles can be changed with the circle_kwargs dictionary, which is
-   supplied to the Matplotlib patch Circle.  One can label each of the halos
-   with the annotate_field, which accepts a field contained in the halo catalog
-   to add text to the plot near the halo (example: ``annotate_field=
-   'particle_mass'`` will write the halo mass next to each halo, whereas
-   ``'particle_identifier'`` shows the halo number). The size of the circles is
-   found from the field ``radius_field`` which is ``'virial_radius'`` by
-   default. If another radius has been found as part of your halo analysis
-   workflow, you can save that field and use it as the ``radius_field`` to
-   change the size of the halos. The position of each halo is determined using
-   ``center_field_prefix`` in the following way. If ``'particle_position'``
-   is the value of ``center_field_prefix`` as is the default, the x value of
-   the halo position is stored in the field ``'particle_position_x'``, y is
-   ``'particle_position_y'``, and z is ``'particle_position_z'``. If you have
-   stored another set of coordinates for each halo as part of your halo
-   analysis as fields such as ``'halo_position_x'``, you can use these fields
-   to determine halo position by passing ``'halo_position'`` to
-   ``center_field_prefix``. font_kwargs contains the arguments controlling the
-   text appearance of the annotated field. Factor is the number the virial
-   radius is multiplied by for plotting the circles. Ex: ``factor=2.0`` will
-   plot circles with twice the radius of each halo virial radius.
-
-.. python-script::
-
-   import yt
-
-   data_ds = yt.load("Enzo_64/RD0006/RedshiftOutput0006")
-   halos_ds = yt.load("rockstar_halos/halos_0.0.bin")
-
-   prj = yt.ProjectionPlot(data_ds, "z", ("gas", "density"))
-   prj.annotate_halos(halos_ds, annotate_field="particle_identifier")
-   prj.save()
 
 .. _annotate-image-line:
 

yt/visualization/plot_modifications.py

@@ -7,6 +7,7 @@
 import matplotlib
 import numpy as np
 
+from yt._maintenance.deprecation import issue_deprecation_warning
 from yt.data_objects.data_containers import YTDataContainer
 from yt.data_objects.level_sets.clump_handling import Clump
 from yt.data_objects.selection_objects.cut_region import YTCutRegion
@@ -1940,6 +1941,14 @@ def __init__(
         font_kwargs=None,
         factor=1.0,
     ):
+        issue_deprecation_warning(
+            "The annotate_halos method has been fully migrated to the "
+            "yt_astro_analysis extension. "
+            "Please update the extension to version 1.1 or newer. "
+            "This duplicated functionality will be removed from the main yt package.",
+            since="4.1",
+            removal="4.2",
+        )
 
         try:
             from yt_astro_analysis.halo_analysis.api import HaloCatalog