Deprecate unused EBSD metadata, remove EBSD.rebin() overriding HyperSpy

README.md

@@ -16,7 +16,7 @@ multi-dimensional data analysis provided by the HyperSpy library.
 [![PyPI version](https://img.shields.io/pypi/v/kikuchipy.svg)](https://pypi.python.org/pypi/kikuchipy)
 [![Downloads per month](https://pepy.tech/badge/kikuchipy/month)](https://pepy.tech/project/kikuchipy)
 [![Zenodo DOI](https://zenodo.org/badge/doi/10.5281/zenodo.3597646.svg)](https://doi.org/10.5281/zenodo.3597646)
-[![All Contributors](https://img.shields.io/badge/all_contributors-5-b1aee3.svg)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/contributors-5-b1aee3.svg)](#contributors-)
 
 - **User guide and API reference**: https://kikuchipy.org. The guide consists of Jupyter
   Notebooks with many links to detailed explanations of the input parameters and output

doc/changelog.rst

@@ -56,6 +56,14 @@ Changed
 - URLs of user guide topics have an extra "/user_guide/<topic>" added to them.
   (`#403 <https://github.com/pyxem/kikuchipy/pull/403>`_)
 
+Deprecated
+----------
+- Custom EBSD metadata, meaning the *Acquisition_instrument.SEM.EBSD.Detector* and
+  *Sample.Phases* nodes, as well as the EBSD *set_experimental_parameters()* and
+  *set_phase_parameters()* methods. This will be removed in v0.6 The *static_background*
+  metadata array will become available as an EBSD property.
+  (`#428 <https://github.com/pyxem/kikuchipy/pull/428>`_)
+
 Removed
 -------
 - *make_similarity_metric()* function is replaced by the need to create a class inheriting

doc/reference.rst

@@ -508,7 +508,6 @@ See :class:`̃hyperspy._signals.signal2d.Signal2D` for methods inherited from Hy
     get_virtual_bse_intensity
     normalize_intensity
     plot_virtual_bse_intensity
-    rebin
     refine_orientation
     refine_orientation_projection_center
     refine_projection_center

doc/user_guide/change_navigation_signal_shapes.ipynb

@@ -51,7 +51,7 @@
     "print(s)\n",
     "\n",
     "s_mp = kp.data.nickel_ebsd_master_pattern_small(hemisphere=\"both\")\n",
-    "print(s_mp, s_mp.projection)"
+    "print(s_mp)"
    ]
   },
   {
@@ -144,8 +144,8 @@
     "## Binning\n",
     "\n",
     "A new `EBSD` signal with patterns binned e.g. by 2 can be obtained using the\n",
-    "[rebin()](../reference.rst#kikuchipy.signals.EBSD.rebin) method provided by\n",
-    "HyperSpy, explained further in\n",
+    "[rebin()](http://hyperspy.org/hyperspy-doc/current/api/hyperspy.signal.html#hyperspy.signal.BaseSignal.rebin)\n",
+    "method provided by HyperSpy, explained further in\n",
     "[their user guide](http://hyperspy.org/hyperspy-doc/current/user_guide/signal.html#rebinning),\n",
     "by passing in either the `scale` or `new_shape` parameter"
    ]
@@ -223,7 +223,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.9.6"
   }
  },
  "nbformat": 4,

doc/user_guide/load_save_data.ipynb

@@ -198,6 +198,29 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "Warning\n",
+    "\n",
+    "The `Acquisition_instrument.SEM.Detector.EBSD` and `Sample.Phases` metadata\n",
+    "nodes are deprecated and will be removed in v0.6.\n",
+    "\n",
+    "There are three main reasons for this change: the first is that only the static\n",
+    "background array stored in the\n",
+    "`Acquisition_instrument.SEM.Detector.EBSD.static_background` node is used\n",
+    "internally, and so the remaining metadata is unnecessary. The background pattern\n",
+    "will be stored in its own `EBSD.static_background` property instead. The second\n",
+    "is that keeping track of the unnecessary metadata makes writing and maintaining\n",
+    "input/ouput plugins challenging. The third is that the\n",
+    "[EBSD.xmap](../reference.rst#kikuchipy.signals.EBSD.xmap) and\n",
+    "[EBSD.detector](../reference.rst#kikuchipy.signals.EBSD.detector) properties,\n",
+    "which keeps track of the\n",
+    "[CrystalMap](https://orix.readthedocs.io/en/stable/reference.html#orix.crystal_map.CrystalMap)\n",
+    "and [EBSDDetector](../reference.rst#kikuchipy.detectors.EBSDDetector) for a\n",
+    "signal, respectively, should be used instead of the more \"static\" metadata.\n",
+    "\n",
+    "</div>\n",
+    "\n",
     "The number of patterns in horizontal and vertical direction, pattern size in\n",
     "pixels, scan step size and detector pixel size is stored in the `axes_manager`\n",
     "attribute:"
@@ -1080,7 +1103,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.9.6"
   }
  },
  "nbformat": 4,

doc/user_guide/metadata_structure.ipynb

@@ -16,6 +16,29 @@
    "source": [
     "# Metadata structure\n",
     "\n",
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "Warning\n",
+    "\n",
+    "The `Acquisition_instrument.SEM.Detector.EBSD` and `Sample.Phases` metadata\n",
+    "nodes are deprecated and will be removed in v0.6.\n",
+    "\n",
+    "There are three main reasons for this change: the first is that only the static\n",
+    "background array stored in the\n",
+    "`Acquisition_instrument.SEM.Detector.EBSD.static_background` node is used\n",
+    "internally, and so the remaining metadata is unnecessary. The background pattern\n",
+    "will be stored in its own `EBSD.static_background` property instead. The second\n",
+    "is that keeping track of the unnecessary metadata makes writing and maintaining\n",
+    "input/ouput plugins challenging. The third is that the\n",
+    "[EBSD.xmap](../reference.rst#kikuchipy.signals.EBSD.xmap) and\n",
+    "[EBSD.detector](../reference.rst#kikuchipy.signals.EBSD.detector) properties,\n",
+    "which keeps track of the\n",
+    "[CrystalMap](https://orix.readthedocs.io/en/stable/reference.html#orix.crystal_map.CrystalMap)\n",
+    "and [EBSDDetector](../reference.rst#kikuchipy.detectors.EBSDDetector) for a\n",
+    "signal, respectively, should be used instead of the more \"static\" metadata.\n",
+    "\n",
+    "</div>\n",
+    "\n",
     "The [EBSD](../reference.rst#kikuchipy.signals.EBSD) class stores metadata in the\n",
     "`metadata` attribute provided by HyperSpy"
    ]
@@ -236,7 +259,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -250,7 +273,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.9.6"
   }
  },
  "nbformat": 4,

doc/user_guide/pattern_processing.ipynb

@@ -134,6 +134,29 @@
     "lowest to 0), while the rest is rescaled keeping relative intensities between\n",
     "patterns. With `relative=False`, all patterns are stretched to [0, 255].\n",
     "\n",
+    "<div class=\"alert alert-warning\">\n",
+    "\n",
+    "Warning\n",
+    "\n",
+    "The `Acquisition_instrument.SEM.Detector.EBSD` and `Sample.Phases` metadata\n",
+    "nodes are deprecated and will be removed in v0.6.\n",
+    "\n",
+    "There are three main reasons for this change: the first is that only the static\n",
+    "background array stored in the\n",
+    "`Acquisition_instrument.SEM.Detector.EBSD.static_background` node is used\n",
+    "internally, and so the remaining metadata is unnecessary. The background pattern\n",
+    "will be stored in its own `EBSD.static_background` property instead. The second\n",
+    "is that keeping track of the unnecessary metadata makes writing and maintaining\n",
+    "input/ouput plugins challenging. The third is that the\n",
+    "[EBSD.xmap](../reference.rst#kikuchipy.signals.EBSD.xmap) and\n",
+    "[EBSD.detector](../reference.rst#kikuchipy.signals.EBSD.detector) properties,\n",
+    "which keeps track of the\n",
+    "[CrystalMap](https://orix.readthedocs.io/en/stable/reference.html#orix.crystal_map.CrystalMap)\n",
+    "and [EBSDDetector](../reference.rst#kikuchipy.detectors.EBSDDetector) for a\n",
+    "signal, respectively, should be used instead of the more \"static\" metadata.\n",
+    "\n",
+    "</div>\n",
+    "\n",
     "The static background pattern intensities can be rescaled to each individual\n",
     "pattern's intensity range before removal by passing `scale_bg=True`, which\n",
     "will result in the relative intensity between patterns to be lost (passing\n",
@@ -736,7 +759,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -750,7 +773,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.10"
+   "version": "3.9.6"
   }
  },
  "nbformat": 4,

kikuchipy/_util/_util.py

@@ -49,7 +49,6 @@ class deprecated:
     def __init__(
         self,
         since: Union[str, int, float],
-        message: Optional[str] = None,
         alternative: Optional[str] = None,
         removal: Union[str, int, float, None] = None,
     ):
@@ -59,16 +58,13 @@ def __init__(
         ----------
         since
             The release at which this API became deprecated.
-        message
-            The deprecation message.
         alternative
             An alternative API that the user may use in place of the
             deprecated API.
         removal
             The expected removal version.
         """
         self.since = since
-        self.message = message
         self.alternative = alternative
         self.removal = removal
 
@@ -88,7 +84,7 @@ def __call__(self, func: Callable):
         @functools.wraps(func)
         def wrapped(*args, **kwargs):
             warnings.simplefilter(
-                action="always", category=np.VisibleDeprecationWarning
+                action="always", category=np.VisibleDeprecationWarning, append=True
             )
             func_code = func.__code__
             warnings.warn_explicit(

kikuchipy/_util/test_util.py

@@ -29,7 +29,7 @@ def test_deprecation_since(self):
         gets the desired additions to their docstring.
         """
 
-        @deprecated(since=0.7, message="Hello", alternative="bar", removal=0.8)
+        @deprecated(since=0.7, alternative="bar", removal=0.8)
         def foo(n):
             """Some docstring."""
             return n + 1
@@ -71,7 +71,7 @@ def foo2(n):
         )
 
     def test_deprecation_no_old_doc(self):
-        @deprecated(since=0.7, message="Hello", alternative="bar", removal=0.8)
+        @deprecated(since=0.7, alternative="bar", removal=0.8)
         def foo(n):
             return n + 1
 

kikuchipy/pattern/_pattern.py

@@ -111,7 +111,7 @@ def remove_dynamic_background(
     filter_domain: str = "frequency",
     std: Union[None, int, float] = None,
     truncate: Union[int, float] = 4.0,
-    dtype_out: Union[None, np.dtype, Tuple[int, int], Tuple[float, float]] = None,
+    dtype_out: Union[None, np.dtype, type, Tuple[int, int], Tuple[float, float]] = None,
 ) -> np.ndarray:
     """Remove the dynamic background in an EBSD pattern.
 

kikuchipy/signals/ebsd.py

@@ -120,7 +120,9 @@ def __init__(self, *args, **kwargs):
             md.update(ebsd_metadata().as_dictionary())
             self.metadata = DictionaryTreeBrowser(md)
         if not self.metadata.has_item("Sample.Phases"):
-            self.set_phase_parameters()
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=np.VisibleDeprecationWarning)
+                self.set_phase_parameters()
 
     # ---------------------- Custom properties ----------------------- #
 
@@ -159,6 +161,7 @@ def xmap(self, value: CrystalMap):
 
     # ------------------------ Custom methods ------------------------ #
 
+    @deprecated(since="0.5", removal="0.6")
     def set_experimental_parameters(
         self,
         detector=None,
@@ -245,8 +248,8 @@ def set_experimental_parameters(
         >>> node = kp.signals.util.metadata_nodes("ebsd")
         >>> s.metadata.get_item(node + '.xpc')
         -5.64
-        >>> s.set_experimental_parameters(xpc=0.50726)
-        >>> s.metadata.get_item(node + '.xpc')
+        >>> s.set_experimental_parameters(xpc=0.50726)  # doctest: +SKIP
+        >>> s.metadata.get_item(node + '.xpc')  # doctest: +SKIP
         0.50726
         """
         md = self.metadata
@@ -285,6 +288,7 @@ def set_experimental_parameters(
             ebsd_node,
         )
 
+    @deprecated(since="0.5", removal="0.6")
     def set_phase_parameters(
         self,
         number=1,
@@ -358,8 +362,8 @@ def set_phase_parameters(
         ...         'site_occupation': 1,
         ...         'debye_waller_factor': 0.005
         ...     }}
-        ... )
-        >>> s.metadata.Sample.Phases.Number_1.atom_coordinates.Number_1
+        ... )  # doctest: +SKIP
+        >>> s.metadata.Sample.Phases.Number_1.atom_coordinates.Number_1  # doctest: +SKIP
         ├── atom = Fe
         ├── coordinates = array([0, 0, 0])
         ├── debye_waller_factor = 0.005
@@ -2049,33 +2053,6 @@ def get_decomposition_model(
 
         return s_model
 
-    def rebin(self, new_shape=None, scale=None, crop=True, out=None):
-        s_out = super().rebin(new_shape=new_shape, scale=scale, crop=crop, out=out)
-
-        return_signal = True
-        if s_out is None:
-            s_out = out
-            return_signal = False
-
-        # Update binning in metadata to signal dimension with largest or
-        # lowest binning if downscaling or upscaling, respectively
-        md = s_out.metadata
-        ebsd_node = metadata_nodes("ebsd")
-        if scale is None:
-            sx, sy = self.axes_manager.signal_shape
-            signal_idx = self.axes_manager.signal_indices_in_array
-            scale = (sx / new_shape[signal_idx[0]], sy / new_shape[signal_idx[1]])
-        upscaled_dimensions = np.where(np.array(scale) < 1)[0]
-        if len(upscaled_dimensions):
-            new_binning = np.min(scale)
-        else:
-            new_binning = np.max(scale)
-        original_binning = abs(md.get_item(ebsd_node + ".binning"))
-        md.set_item(ebsd_node + ".binning", original_binning * new_binning)
-
-        if return_signal:
-            return s_out
-
     # ------------------------ Private methods ----------------------- #
 
     def _check_refinement_parameters(

kikuchipy/signals/tests/test_ebsd.py

@@ -742,40 +742,6 @@ def test_average_neighbour_patterns_lazy(self):
         s.compute()
 
 
-class TestRebin:
-    def test_rebin(self, dummy_signal):
-        ebsd_node = kp.signals.util.metadata_nodes("ebsd")
-
-        # Passing new_shape, only scaling in signal space
-        new_shape = (3, 3, 2, 1)
-        new_binning = dummy_signal.axes_manager.shape[3] / new_shape[3]
-        s2 = dummy_signal.rebin(new_shape=new_shape)
-        assert s2.axes_manager.shape == new_shape
-        assert s2.metadata.get_item(ebsd_node + ".binning") == new_binning
-
-        # Passing scale, also scaling in navigation space
-        scale = (3, 1, 3, 2)
-        s2 = dummy_signal.rebin(scale=scale)
-        expected_new_shape = [
-            int(i / j) for i, j in zip(dummy_signal.axes_manager.shape, scale)
-        ]
-        assert s2.axes_manager.shape == tuple(expected_new_shape)
-        assert s2.metadata.get_item(ebsd_node + ".binning") == float(scale[2])
-
-        # Passing lazy signal to out parameter, only scaling in signal space but
-        # upscaling
-        scale = (1, 1, 1, 0.5)
-        expected_new_shape = [
-            int(i / j) for i, j in zip(dummy_signal.axes_manager.shape, scale)
-        ]
-        s2 = dummy_signal.copy().as_lazy()
-        s3 = dummy_signal.rebin(scale=scale, out=s2)
-        assert isinstance(s2, kp.signals.LazyEBSD)
-        assert s2.axes_manager.shape == tuple(expected_new_shape)
-        assert s2.metadata.get_item(ebsd_node + ".binning") == float(scale[3])
-        assert s3 is None
-
-
 class TestVirtualBackscatterElectronImaging:
     @pytest.mark.parametrize("out_signal_axes", [None, (0, 1), ("x", "y")])
     def test_virtual_backscatter_electron_imaging(self, dummy_signal, out_signal_axes):

kikuchipy/signals/util/_metadata.py

@@ -36,6 +36,10 @@ def ebsd_metadata() -> DictionaryTreeBrowser:
     Returns
     -------
     md : hyperspy.misc.utils.DictionaryTreeBrowser
+
+    Notes
+    -----
+    .. deprecated:: 0.5
     """
     md = DictionaryTreeBrowser()
     sem_node, ebsd_node = metadata_nodes(["sem", "ebsd"])