#!/usr/bin/env python
# coding: utf-8

# This notebook is part of the `kikuchipy` documentation https://kikuchipy.org.
# Links to the documentation won't work from the notebook.

# # Metadata structure
# 
# <div class="alert alert-warning">
# 
# Warning
# 
# The `Acquisition_instrument.SEM.Detector.EBSD` and `Sample.Phases` metadata
# nodes are deprecated and will be removed in v0.6.
# 
# There are three main reasons for this change: the first is that only the static
# background array stored in the
# `Acquisition_instrument.SEM.Detector.EBSD.static_background` node is used
# internally, and so the remaining metadata is unnecessary. The background pattern
# will be stored in its own `EBSD.static_background` property instead. The second
# is that keeping track of the unnecessary metadata makes writing and maintaining
# input/ouput plugins challenging. The third is that the
# [EBSD.xmap](../reference.rst#kikuchipy.signals.EBSD.xmap) and
# [EBSD.detector](../reference.rst#kikuchipy.signals.EBSD.detector) properties,
# which keeps track of the
# [CrystalMap](https://orix.readthedocs.io/en/stable/reference.html#orix.crystal_map.CrystalMap)
# and [EBSDDetector](../reference.rst#kikuchipy.detectors.EBSDDetector) for a
# signal, respectively, should be used instead of the more "static" metadata.
# 
# </div>
# 
# The [EBSD](../reference.rst#kikuchipy.signals.EBSD) class stores metadata in the
# `metadata` attribute provided by HyperSpy

# In[ ]:


# Exchange inline for notebook or qt5 (from pyqt) for interactive plotting
get_ipython().run_line_magic('matplotlib', 'inline')

import matplotlib.pyplot as plt
import kikuchipy as kp


s = kp.data.nickel_ebsd_small()
s


# In[ ]:


s.metadata


# While kikuchipy's EBSD
# ([ebsd_metadata()](../reference.rst#kikuchipy.signals.util.ebsd_metadata)) metadata
# structure is based on
# [HyperSpy's metadata structure](http://hyperspy.org/hyperspy-doc/current/user_guide/metadata_structure.html),
# it includes the nodes `Acquisition_instrument.Sample.Phases` to store phase
# information and `Acquisition_instrument.SEM.Detector.EBSD` for acquisition
# information. The information in these nodes are written, along with the
# patterns, to file when saving an EBSD signal in the
# [kikuchipy h5ebsd format](load_save_data.ipynb#h5ebsd).

# In[ ]:


kp.signals.util.ebsd_metadata()


# The complete list of metadata looks like this
# 
# ```
#     ├── Acquisition_instrument
#     │   └── SEM
#     │       ├── Detector
#     │       │   └── EBSD
#     │       │       ├── azimuth_angle [º]
#     │       │       ├── binning
#     │       │       ├── detector
#     │       │       ├── elevation_angle [º]
#     │       │       ├── exposure_time [s]
#     │       │       ├── frame_number
#     │       │       ├── frame_rate [1/s]
#     │       │       ├── gain [dB]
#     │       │       ├── grid_type
#     │       │       ├── manufacturer
#     │       │       ├── sample_tilt [º]
#     │       │       ├── scan_time [s]
#     │       │       ├── static_background (numpy.ndarray)
#     │       │       ├── version
#     │       │       ├── xpc
#     │       │       ├── ypc
#     │       │       └── zpc
#     │       ├── beam_energy [kV]
#     │       ├── magnification
#     │       ├── microscope
#     │       └── working_distance [mm]
#     └── Sample
#         └── Phases
#             └── 1
#                 ├── atom_coordinates
#                 │   └── 1
#                 │       ├── atom
#                 │       ├── coordinates (x0, y0, z0)
#                 │       ├── debye_waller_factor [nm^2]
#                 │       └── site_occupation
#                 ├── formula
#                 ├── info
#                 ├── lattice_constants (a, b, c and alfa, beta, gamma) [nm and º]
#                 ├── laue_group
#                 ├── material_name
#                 ├── point_group
#                 ├── setting
#                 ├── source
#                 ├── space_group
#                 └── symmetry
# ```

# The utility function
# [metadata_nodes()](../reference.rst#kikuchipy.signals.util.metadata_nodes) returns
# the node strings for the `SEM` and `EBSD` nodes for convenience.
# 
# <div class="alert alert-info">
# 
# Note 
# 
# If you regularly use information relevant to EBSD data not included in the
# metadata structure, you can request this in our
# [issue tracker](https://github.com/pyxem/kikuchipy/issues).
# 
# </div>

# In[ ]:


sem_node, ebsd_node = kp.signals.util.metadata_nodes()
print(sem_node, ebsd_node)


# In[ ]:


s.metadata.get_item(f"{ebsd_node}.xpc")


# In[ ]:


plt.imshow(s.metadata.get_item(f"{ebsd_node}.static_background"), cmap="gray")
_ = plt.axis("off")


# ## EBSD
# 
# This node contains information relevant for EBSD data. All parameters can be
# set with the method
# [set_experimental_parameters()](../reference.rst#kikuchipy.signals.EBSD.set_experimental_parameters).
# An explanation of each parameter is given in the method's docstring.

# In[ ]:


s.set_experimental_parameters(xpc=5.64)
s.metadata.get_item(f"{ebsd_node}.xpc")


# ## Phases
# 
# This node contains information relevant for EBSD scans or simulated patterns'
# phases. All parameters can be set with the
# [EBSD](../reference.rst#kikuchipy.signals.EBSD) class method
# [set_phase_parameters()](../reference.rst#kikuchipy.signals.EBSD.set_phase_parameters).
# An explanation of each parameter is given in the methods' docstring.

# In[ ]:


s.metadata.Sample.Phases


# In[ ]:


s.set_phase_parameters(info="Polycrystalline")
s.metadata.Sample.Phases