This page was generated from doc/user_guide/metadata_structure.ipynb. Interactive online version: Binder badge.

Metadata structure

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 and EBSD.detector properties, which keeps track of the CrystalMap and EBSDDetector for a signal, respectively, should be used instead of the more “static” metadata.

The EBSD class stores metadata in the metadata attribute provided by HyperSpy

[1]:
# Exchange inline for notebook or qt5 (from pyqt) for interactive plotting
%matplotlib inline

import matplotlib.pyplot as plt
import kikuchipy as kp


s = kp.data.nickel_ebsd_small()
s
WARNING:hyperspy.api:The ipywidgets GUI elements are not available, probably because the hyperspy_gui_ipywidgets package is not installed.
WARNING:hyperspy.api:The traitsui GUI elements are not available, probably because the hyperspy_gui_traitsui package is not installed.
[1]:
<EBSD, title: patterns My awes0m4 ..., dimensions: (3, 3|60, 60)>
[2]:
s.metadata
[2]:
  • Acquisition_instrument
    • SEM
      • Detector
        • EBSD
          • azimuth_angle = 0.0
          • binning = 8
          • detector = NORDIF UF1100
          • elevation_angle = 0.0
          • exposure_time = 0.0035
          • frame_number = 1
          • frame_rate = 202
          • gain = 0.0
          • grid_type = square
          • manufacturer = kikuchipy
          • sample_tilt = 70.0
          • scan_time = 148
          • static_background = array([[84, 87, 90, ..., 27, 29, 30], [87, 90, 93, ..., 27, 28, 30], ... 80, 82, ..., 28, 26, 26], [76, 78, 80, ..., 26, 26, 25]], dtype=uint8)
          • version = 0.1
          • xpc = -5.64
          • ypc = 17.28
          • zpc = 2087
      • beam_energy = 20.0
      • magnification = 200
      • microscope = Hitachi SU-6600
      • working_distance = 24.7
  • General
    • title = patterns My awes0m4 ...
  • Sample
    • Phases
      • 1
        • atom_coordinates
          • 1
            • atom = Ni
            • coordinates = array([0, 0, 0])
            • debye_waller_factor = 0.0035
            • site_occupation = 1
        • formula = Ni
        • info =
        • lattice_constants = array([ 0.35236, 0.35236, 0.35236, 90. , 90. , 90. ])
        • laue_group =
        • material_name = Ni
        • point_group =
        • setting = 0
        • space_group = 225
        • symmetry = 0
  • Signal
    • binned = False
    • signal_type = EBSD

While kikuchipy’s EBSD (ebsd_metadata()) metadata structure is based on HyperSpy’s metadata structure, 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.

[3]:
kp.signals.util.ebsd_metadata()
[3]:
  • Acquisition_instrument
    • SEM
      • Detector
        • EBSD
          • azimuth_angle = -1.0
          • binning = 1
          • detector =
          • elevation_angle = -1.0
          • exposure_time = -1
          • frame_number = -1
          • frame_rate = -1
          • gain = -1.0
          • grid_type =
          • sample_tilt = -1.0
          • scan_time = -1.0
          • static_background = -1
          • xpc = -1.0
          • ypc = -1.0
          • zpc = -1.0
      • beam_energy = -1.0
      • magnification = -1
      • microscope =
      • working_distance = -1.0

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() returns the node strings for the SEM and EBSD nodes for convenience.

Note

If you regularly use information relevant to EBSD data not included in the metadata structure, you can request this in our issue tracker.

[4]:
sem_node, ebsd_node = kp.signals.util.metadata_nodes()
print(sem_node, ebsd_node)
Acquisition_instrument.SEM Acquisition_instrument.SEM.Detector.EBSD
[5]:
s.metadata.get_item(f"{ebsd_node}.xpc")
[5]:
-5.64
[6]:
plt.imshow(s.metadata.get_item(f"{ebsd_node}.static_background"), cmap="gray")
_ = plt.axis("off")
../_images/user_guide_metadata_structure_10_0.png

EBSD

This node contains information relevant for EBSD data. All parameters can be set with the method set_experimental_parameters(). An explanation of each parameter is given in the method’s docstring.

[7]:
s.set_experimental_parameters(xpc=5.64)
s.metadata.get_item(f"{ebsd_node}.xpc")
/home/docs/checkouts/readthedocs.org/user_builds/kikuchipy/envs/latest/lib/python3.8/site-packages/kikuchipy/signals/ebsd.py:165: VisibleDeprecationWarning: Function `set_experimental_parameters()` is deprecated and will be removed in version 0.6.
  def set_experimental_parameters(
[7]:
5.64

Phases

This node contains information relevant for EBSD scans or simulated patterns’ phases. All parameters can be set with the EBSD class method set_phase_parameters(). An explanation of each parameter is given in the methods’ docstring.

[8]:
s.metadata.Sample.Phases
[8]:
  • 1
    • atom_coordinates
      • 1
        • atom = Ni
        • coordinates = array([0, 0, 0])
        • debye_waller_factor = 0.0035
        • site_occupation = 1
    • formula = Ni
    • info =
    • lattice_constants = array([ 0.35236, 0.35236, 0.35236, 90. , 90. , 90. ])
    • laue_group =
    • material_name = Ni
    • point_group =
    • setting = 0
    • space_group = 225
    • symmetry = 0
[9]:
s.set_phase_parameters(info="Polycrystalline")
s.metadata.Sample.Phases
/home/docs/checkouts/readthedocs.org/user_builds/kikuchipy/envs/latest/lib/python3.8/site-packages/kikuchipy/signals/ebsd.py:292: VisibleDeprecationWarning: Function `set_phase_parameters()` is deprecated and will be removed in version 0.6.
  def set_phase_parameters(
[9]:
  • 1
    • atom_coordinates
      • 1
        • atom = Ni
        • coordinates = array([0, 0, 0])
        • debye_waller_factor = 0.0035
        • site_occupation = 1
    • formula = Ni
    • info = Polycrystalline
    • lattice_constants = array([ 0.35236, 0.35236, 0.35236, 90. , 90. , 90. ])
    • laue_group =
    • material_name = Ni
    • point_group =
    • setting = 0
    • space_group = 225
    • symmetry = 0