Merge pull request #628 from Erlendos12/display_pc_convention

Better inform about PC convention used in kikuchipy (Bruker's)
pyxem · Mar 23, 2023 · 9ccf7ad · 9ccf7ad
2 parents 92e52a9 + 5e6803c
commit 9ccf7ad
Show file tree

Hide file tree

Showing 13 changed files with 313 additions and 264 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -13,6 +13,14 @@ its best to adhere to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>
 List entries are sorted in descending chronological order. Contributors to each release
 were listed in alphabetical order by first name until version 0.7.0.
 
+0.8.3 (2023-03-23)
+==================
+
+Changed
+-------
+- ``EBSD.hough_indexing()`` info message now informs that the given projection center is
+  in Bruker's convention. (`#628 <https://github.com/pyxem/kikuchipy/pull/628>`_)
+
 0.8.2 (2023-03-14)
 ==================
 

diff --git a/RELEASE.rst b/RELEASE.rst
@@ -2,59 +2,72 @@ How to make a new release of ``kikuchipy``
 ==========================================
 
 kikuchipy's branching model is similar to the Gitflow Workflow (`original blog post
-<https://nvie.com/posts/a-successful-git-branching-model/>`_).
+<https://nvie.com/posts/a-successful-git-branching-model/>`__).
+
+kikuchipy versioning tries its best to adhere to `Semantic Versioning
+<https://semver.org/spec/v2.0.0.html>`__.
+See the `Python Enhancement Proposal (PEP) 440 <https://peps.python.org/pep-0440/>`__
+for supported version identifiers.
 
 Preparation
 -----------
-- If a minor release is to be made, create a release branch named e.g.
-  ``v<major>.<minor>.0`` off of the ``develop`` branch locally.
-  If a patch release is to be made, create a release branch ``v<major>.<minor>.<patch>``
-  off of the ``main`` branch locally instead.
-  Ideally, a patch release should be made immediately after a bug fix has been made.
-  Therefore, it might be best to do the release updates, listed in the following steps,
-  directly on the bug fix branch, so that no separate patch release branch has to be
-  made.
-  The bug fix branch should of course be branched off of ``main``.
-- Run all user guide notebooks locally and confirm that they produce the expected
-  results.
-- Review the contributor list ``__credits__`` in ``release.py`` to ensure all
+- Locally, create a minor release branch from the ``develop`` branch when making a minor
+  release, or create a patch release branch from the ``main`` branch when making a patch
+  release. Ideally, a patch release is published immediately after a bug fix is merged
+  in ``main``. Therefore, it might be best to do the release updates directly on the bug
+  fix branch, so that no separate patch release branch has to be made.
+
+- Run tutorial notebooks and examples in the documentation locally and confirm that they
+  produce the expected results.
+  From time to time, check the documentation links (``make linkchecker``) and fix any
+  broken ones.
+
+- Review the contributor list ``__credits__`` in ``kikuchipy/release.py`` to ensure all
   contributors are included and sorted correctly.
   Do the same for the Zenodo contributors file ``.zenodo.json``.
   Review ``.all-contributorsrc`` and regenerate the table if necessary.
-- Increment the version number in ``release.py``.
+
+- Increment the version number in ``kikuchipy/release.py``.
   Review and clean up ``CHANGELOG.rst`` as per Keep a Changelog.
+
 - Make a PR of the release branch to ``main``.
   Discuss the changelog with others, and make any changes *directly* to the release
   branch.
   Merge the branch onto ``main``.
 
-Release (and tag)
------------------
-- If the ``__version__`` in ``release.py`` on ``main`` has changed in a new commit, a
-  tagged, annotated release *draft* is automatically created.
+Tag and release
+---------------
+- If the ``__version__`` in ``kikuchipy/release.py`` on ``main`` has changed in a new
+  commit, a tagged, annotated release *draft* is automatically created.
   If ``__version__`` is now "0.42.0", the release name is "kikuchipy 0.42.0", and the
   tag name is "v0.42.0".
   The tag target will be the ``main`` branch.
   The release body contains a static description and a link to the changelog.
   This release draft can be published as is, or changes to the release body can be made
   before publishing.
-- Monitor the publish GitHub Action to ensure the release is successfully published to
-  PyPI.
+
+- Monitor the publish workflow to ensure the release is successfully published to PyPI.
 
 Post-release action
 -------------------
-- Monitor the `documentation build <https://readthedocs.org/projects/kikuchipy/builds>`_
-  to make sure the new stable documentation is successfully built from the release.
-- Ensure that `Zenodo <https://doi.org/10.5281/zenodo.3597646>`_ received the new
+- Monitor the `documentation build <https://readthedocs.org/projects/kikuchipy/builds>`__
+  ensure that the new stable documentation is successfully built from the release.
+
+- Ensure that `Zenodo <https://doi.org/10.5281/zenodo.3597646>`__ displays the new
   release.
+
 - Ensure that Binder can run the user guide notebooks by clicking the Binder badges in
-  the top banner of one of the user guide notebooks via `Read The Docs
-  <https://kikuchipy.org/en/stable>`_.
-- Bring changes on ``main`` onto ``develop`` by branching off of ``main``, merge
-  ``develop`` onto the new branch, fix conflicts, and make a PR to ``develop``.
-- Make a post-release PR to ``develop`` with ``__version__`` updated (or reverted), e.g.
-  from "0.42.0" to "0.43.dev0", and any updates to this guide if necessary.
+  the top banner of one of the tutorials via `Read The Docs
+  <https://kikuchipy.org/en/stable>`__.
+
+- Bring changes on ``main`` into ``develop`` by branching from ``main``, merge
+  ``develop`` into the new branch and fix potential conflicts.
+  After these conflicts are fixed, update or revert ``__version__`` and make any updates
+  to this guide if necessary.
+  Make a PR to ``develop`` and merge.
+
 - Tidy up GitHub issues and close the corresponding milestone.
+
 - A PR to the conda-forge feedstock will be created by the conda-forge bot.
   Follow the relevant instructions from the conda-forge documentation on updating
   packages, as well as the instructions in the PR.

diff --git a/doc/dev/report_handling_manual.rst b/doc/dev/report_handling_manual.rst
@@ -230,5 +230,5 @@ Endnotes
 We are thankful to the groups behind the following documents, from which we drew
 content and inspiration:
 
-* `napari Code of Conduct - How to follow up on a report <https://github.com/napari/napari/blob/main/docs/community/code_of_conduct_reporting.md>`_
+* `napari Code of Conduct - How to follow up on a report <https://napari.org/stable/community/code_of_conduct_reporting.html>`_
 * `NumPy Code of Conduct - How to follow up on a report <https://numpy.org/report-handling-manual>`_
diff --git a/doc/tutorials/hybrid_indexing.ipynb b/doc/tutorials/hybrid_indexing.ipynb
diff --git a/doc/tutorials/load_save_data.ipynb b/doc/tutorials/load_save_data.ipynb
@@ -387,7 +387,7 @@
     "## Save patterns\n",
     "\n",
     "To save signals to file, use the [save()](../reference/generated/kikuchipy.signals.EBSD.save.rst) method.\n",
-    "For example, to save an `EBSD` signal in an HDF5 file, with file name `\"patterns.h5\"`, in our default [h5ebsd format](#kikuchipy-h5ebsd)"
+    "For example, to save an `EBSD` signal in an HDF5 file in our default [h5ebsd format](#kikuchipy-h5ebsd), with file name `\"patterns.h5\"`"
    ]
   },
   {
@@ -701,7 +701,7 @@
     "Other supported h5ebsd formats are listed in the [table above](#Supported-file-formats).\n",
     "\n",
     "If an h5ebsd file contains multiple scans, as many scans as desirable can be read from the file.\n",
-    "For example, if the file contains two scans with names `\"My awes0m4 Xcan #! with a long title\"` and `\"Scan 2\"`"
+    "For example, if the file contains two scans with names `\"Scan 1\"` and `\"Scan 2\"`"
    ]
   },
   {

diff --git a/doc/tutorials/pc_extrapolate_plane.ipynb b/doc/tutorials/pc_extrapolate_plane.ipynb
diff --git a/doc/tutorials/pc_fit_plane.ipynb b/doc/tutorials/pc_fit_plane.ipynb
diff --git a/doc/tutorials/pc_orientation_dependence.ipynb b/doc/tutorials/pc_orientation_dependence.ipynb
diff --git a/doc/user/applications.rst b/doc/user/applications.rst
@@ -14,18 +14,17 @@ Most of these works are also listed when searching for ``"kikuchipy"`` `on Googl
 
 2023
 ====
+- H. W. Ånes, A. T. J. van Helvoort and K. Marthinsen, "Orientation dependent pinning
+  of (sub)grains by dispersoids during recovery and recrystallization in an Al-Mn
+  alloy," *Acta Materialia* **248** (2023).
+  https://doi.org/10.1016/j.actamat.2023.118761.
 - T. Bergh, H. W. Ånes, R. Aune, S. Wenner, R. Holmestad, X. Ren and P. E. Vullum,
   "Intermetallic Phase Layers in Cold Metal Transfer Aluminium-Steel Welds with an
   Al-Si–Mn Filler Alloy," *Materials Transactions* **64(2)** (2023).
   https://doi.org/10.2320/matertrans.MT-LA2022046.
 
 2022
 ====
-
-- H. W. Ånes, A. T. J. van Helvoort and K. Marthinsen, "Orientation dependent pinning
-  of (sub)grains by dispersoids during recovery and recrystallization in an Al-Mn
-  alloy," *Acta Materialia* 118761 (2023).
-  https://doi.org/10.1016/j.actamat.2023.118761.
 - O. M. Akselsen, R. Bjørge, H. W. Ånes, X. Ren, and B. Nyhus, "Microstructure and
   Properties of Wire Arc Additive Manufacturing of Inconel 625," *Metals* **12(11)**
   (2022).
@@ -36,7 +35,7 @@ Most of these works are also listed when searching for ``"kikuchipy"`` `on Googl
   https://doi.org/10.1016/j.matchar.2022.112228.
 - J. Schultheiß, F. Xue, E. Roede, H. W. Ånes, F. H. Danmo, S. M. Selbach, L.-Q. Chen
   and D. Meier, "Confinement-driven inverse domain scaling in polycrystalline ErMnO3,"
-  *Advanced Materials*, 2203449 (2022).
+  *Advanced Materials*, **34** (2022).
   https://doi.org/10.1002/adma.202203449.
 
 2021

diff --git a/kikuchipy/detectors/ebsd_detector.py b/kikuchipy/detectors/ebsd_detector.py
@@ -69,38 +69,41 @@ class EBSDDetector:
         Number of detector rows and columns in pixels. Default is
         (1, 1).
     px_size
-        Size of unbinned detector pixel in um, assuming a square
-        pixel shape. Default is 1.
+        Size of unbinned detector pixel in um, assuming a square pixel
+        shape. Default is 1.
     binning
         Detector binning, i.e. how many pixels are binned into one.
         Default is 1, i.e. no binning.
     tilt
         Detector tilt from horizontal in degrees. Default is 0.
     azimuthal
         Sample tilt about the sample RD (downwards) axis. A positive
-        angle means the sample normal moves towards the right
-        looking from the sample to the detector. Default is 0.
+        angle means the sample normal moves towards the right looking
+        from the sample to the detector. Default is 0.
     sample_tilt
         Sample tilt from horizontal in degrees. Default is 70.
     pc
-        X, Y and Z coordinates of the projection/pattern centers
-        (PCs), describing the location of the beam on the sample
-        measured relative to the detection screen. See *Notes* for
-        the definition and conversions between conventions. If
-        multiple PCs are passed, they are assumed to be on the form
+        X, Y and Z coordinates of the projection/pattern centers (PCs),
+        describing the location of the beam on the sample measured
+        relative to the detection screen. PCs are stored and used in
+        Bruker's convention. See *Notes* for the definition and
+        conversions between conventions. If multiple PCs are passed,
+        they are assumed to be on the form
         [[x0, y0, z0], [x1, y1, z1], ...]. Default is [0.5, 0.5, 0.5].
     convention
-        PC convention. If not given, Bruker's convention is assumed.
-        Options are "tsl"/"edax"/"amatek", "oxford"/"aztec", "bruker",
-        "emsoft", "emsoft4", and "emsoft5". "emsoft" and "emsoft5" is
-        the same convention. See *Notes* for conversions between
-        conventions.
+        Convention of input PC, to determine which conversion to
+        Bruker's definition to use. If not given, Bruker's convention is
+        assumed. Options are "tsl"/"edax"/"amatek", "oxford"/"aztec",
+        "bruker", "emsoft", "emsoft4", and "emsoft5". "emsoft" and
+        "emsoft5" is the same convention. See *Notes* for conversions
+        between conventions.
 
     Notes
     -----
     The pattern on the detector is always viewed *from* the detector
-    *towards*  the sample. Pattern width and height is here given as
-    :math:`N_x` and :math:`N_y` (possibly binned).
+    *towards* the sample. Pattern width and height is here given as
+    :math:`N_x` and :math:`N_y` (possibly binned). PCs are stored and
+    used in Bruker's convention.
 
     The Bruker PC coordinates :math:`(x_B^*, y_B^*, z_B^*)` are defined
     in fractions of :math:`N_x`, :math:`N_y`, and :math:`N_y`,
@@ -263,14 +266,16 @@ def pc(self) -> np.ndarray:
         ----------
         value : numpy.ndarray, list or tuple
             Projection center coordinates. If multiple PCs are passed,
-            they are assumed to be on the form ``[[x0, y0, z0],
-            [x1, y1, z1], ...]``. Default is ``[[0.5, 0.5, 0.5]]``.
+            they are assumed to be on the form [[x0, y0, z0],
+            [x1, y1, z1], ...]. Default is [[0.5, 0.5, 0.5]].
         """
         return self._pc
 
     @pc.setter
     def pc(self, value: Union[np.ndarray, List, Tuple]):
-        """Set all projection center coordinates."""
+        """Set all projection center coordinates, assuming Bruker's
+        convention.
+        """
         self._pc = np.atleast_2d(value)
 
     @property
@@ -287,9 +292,9 @@ def pcx(self) -> np.ndarray:
         Parameters
         ----------
         value : numpy.ndarray, list, tuple or float
-            Projection center x coordinates. If multiple x coordinates
-            are passed, they are assumed to be on the form
-            ``[x0, x1,...]``.
+            Projection center x coordinates in Bruker's convention. If
+            multiple x coordinates are passed, they are assumed to be on
+            the form [x0, x1,...].
         """
         return self.pc[..., 0]
 
@@ -305,9 +310,9 @@ def pcy(self) -> np.ndarray:
         Parameters
         ----------
         value : numpy.ndarray, list, tuple or float
-            Projection center y coordinates. If multiple y coordinates
-            are passed, they are assumed to be on the form
-            ``[y0, y1,...]``.
+            Projection center y coordinates in Bruker's convention. If
+            multiple y coordinates are passed, they are assumed to be on
+            the form [y0, y1,...].
         """
         return self.pc[..., 1]
 
@@ -323,9 +328,9 @@ def pcz(self) -> np.ndarray:
         Parameters
         ----------
         value : numpy.ndarray, list, tuple or float
-            Projection center z coordinates. If multiple z coordinates
-            are passed, they are assumed to be on the form
-            ``[z0, z1,...]``.
+            Projection center z coordinates in Bruker's convention. If
+            multiple z coordinates are passed, they are assumed to be on
+            the form [z0, z1,...].
         """
         return self.pc[..., 2]
 
@@ -380,7 +385,7 @@ def navigation_size(self) -> int:
 
     @property
     def bounds(self) -> np.ndarray:
-        """Return the detector bounds ``[x0, x1, y0, y1]`` in pixel
+        """Return the detector bounds [x0, x1, y0, y1] in pixel
         coordinates.
         """
         return np.array([0, self.ncols - 1, 0, self.nrows - 1])
@@ -417,7 +422,7 @@ def y_range(self) -> np.ndarray:
 
     @property
     def gnomonic_bounds(self) -> np.ndarray:
-        """Return the detector bounds ``[x0, x1, y0, y1]`` in gnomonic
+        """Return the detector bounds [x0, x1, y0, y1] in gnomonic
         coordinates.
         """
         return np.concatenate((self.x_range, self.y_range), axis=-1)
@@ -619,8 +624,8 @@ def estimate_xtilt(
         coincidence with the detector plane normal (but in the opposite
         direction) :cite:`winkelmann2020refined`.
 
-        See the `reference frame tutorial
-        </doc/tutorials/reference_frames.ipynb>`_ for details on the
+        See the :ref:`reference frame tutorial
+        </tutorials/reference_frames.ipynb>` for details on the
         detector sample geometry.
 
         An estimate is found by linear regression of :attr:`pcz` vs.
@@ -753,8 +758,8 @@ def estimate_xtilt_ztilt(
         the detector plane normal (but in the opposite direction)
         :cite:`winkelmann2020refined`.
 
-        See the `reference frame tutorial
-        </doc/tutorials/reference_frames.ipynb>`_ for details on the
+        See the :ref:`reference frame tutorial
+        </tutorials/reference_frames.ipynb>` for details on the
         detector sample geometry.
 
         Estimates are found by fitting a hyperplane to :attr:`pc` using
@@ -1258,7 +1263,8 @@ def plot(
         zoom: float = 1,
         return_figure: bool = False,
     ) -> Union[None, Figure]:
-        """Plot the detector screen.
+        """Plot the detector screen viewed from the detector towards the
+        sample.
 
         The plotting of gnomonic circles and general style is adapted
         from the supplementary material to :cite:`britton2016tutorial`
@@ -1296,7 +1302,7 @@ def plot(
         zoom
             Whether to zoom in/out from the detector, e.g. to show the
             extent of the gnomonic projection circles. A zoom > 1 zooms
-            out. Default is ``1``, i.e. no zoom.
+            out. Default is 1, i.e. no zoom.
         return_figure
             Whether to return the figure. Default is False.
 

diff --git a/kikuchipy/indexing/_hough_indexing.py b/kikuchipy/indexing/_hough_indexing.py
@@ -381,17 +381,17 @@ def _get_info_message(nav_size: int, chunksize: int, indexer: "EBSDIndexer") ->
     info = (
         "Hough indexing with PyEBSDIndex information:\n"
         f"  PyOpenCL: {_pyopencl_context_available}\n"
-        "  Projection center"
+        "  Projection center (Bruker"
     )
 
     n_chunks = int(np.ceil(nav_size / chunksize))
     pc = indexer.PC.squeeze()
     if pc.size > 3:
         pc = pc.mean(0)
-        info += " (mean)"
+        info += ", mean"
     pc = pc.round(4)
     info += (
-        f": {tuple(pc)}\n" f"  Indexing {nav_size} pattern(s) in {n_chunks} chunk(s)"
+        f"): {tuple(pc)}\n" f"  Indexing {nav_size} pattern(s) in {n_chunks} chunk(s)"
     )
 
     return info

diff --git a/kikuchipy/release.py b/kikuchipy/release.py
@@ -37,4 +37,4 @@
 name = "kikuchipy"
 platforms = ["Linux", "MacOS X", "Windows"]
 status = "Development"
-version = "0.8.2"
+version = "0.8.3"
diff --git a/kikuchipy/signals/tests/test_ebsd_hough_indexing.py b/kikuchipy/signals/tests/test_ebsd_hough_indexing.py
@@ -55,7 +55,7 @@ def test_hough_indexing_print_information(self):
         # fmt: off
         assert info_list[0] ==     "Hough indexing with PyEBSDIndex information:"
         assert info_list[1][:12] == "  PyOpenCL: "
-        assert info_list[2] ==     "  Projection center (mean): (0.4251, 0.2134, 0.5007)"
+        assert info_list[2] ==     "  Projection center (Bruker, mean): (0.4251, 0.2134, 0.5007)"
         assert info_list[3] ==     "  Indexing 9 pattern(s) in 3 chunk(s)"
         # fmt: on
 
@@ -66,7 +66,7 @@ def test_hough_indexing_print_information(self):
             self.signal.axes_manager.navigation_size, chunksize=3, indexer=indexer2
         )
         info_list2 = info2.split("\n")
-        assert info_list2[2] == "  Projection center: (0.4251, 0.2134, 0.5007)"
+        assert info_list2[2] == "  Projection center (Bruker): (0.4251, 0.2134, 0.5007)"
 
     def test_hough_indexing(self):
         # Reference results (Hough indexing + refinement)