Roi

Roi

class apav.Roi(xyz, mass, misc=None)

High level container for operating on atom probe data sets.

This data structure is the entry point for loading or constructing atom probe data set for use with other components of APAV. Fictitious atom probe data set can be created by providing the required XYZ and mass/charge arrays, or by the alternate constructors for loading from common file types. For example:

Manual data set:

>>> xyz = np.array([[1.2, 0.3, 12.6], [-76.2, 45.6, 0.7]])
>>> mass = np.array([12.4, 6.1, 14.9])
>>> fake_data = Roi(xyz, mass)

Load from file:

>>> pos_data = Roi.from_pos("path_to_pos_file.pos")  # load a pos file
>>> epos_data = Roi.from_epos("path_to_epos_file.epos")  # load a epos file
>>> ato_data = Roi.from_ato("path_to_ato_file.ato")  # load an ato file

Parameters:

• xyz (ndarray) – xyz atom coordinates

• mass (ndarray) – Mass to charge ratios

• misc (Optional[dict]) – Dict of other data, (i.e. ions per pulse or detector x pos)

property counts: int

Get the total number of detected ions

property detector_extents: Tuple[Tuple[float, float], Tuple[float, float]]

Get the min/max spatial values in x/y detector coordinates

property dimensions: ndarray

Get the x/y/z dimensions of the dataset

property filepath: str

Get the file path, if the Roi was loaded from a file

classmethod from_apt(filepath, verbose=False)

Read the contents of an apt file into a Roi container

Parameters:

• filepath (str) – Path to apt file

• verbose (bool) – Print the structure of the apt file as it is read (for debug purposes)

classmethod from_ato(filepath)

Read the contents of an extended ato file into an Roi container. Suitable for multiple-hit analysis.

Parameters:

filepath (str) – Path to ato file

classmethod from_epos(filepath)

Read the contents of an extended pos file into an Roi container. Suitable for multiple-hit analysis.

Parameters:

filepath (str) – Path to epos file

classmethod from_pos(filepath)

Read the contents of a pos file into a Roi container

Parameters:

filepath (str) – Path to pos file

has_detailed_info()

Get if the Roi has any supplementary information available (other than x/y/z/mass-charge).

Return type:

bool

has_multiplicity_info()

Get if the Roi has multiple detector event information

Return type:

bool

has_tof_info()

Get if the Roi has time of flight information

Return type:

bool

property mass: ndarray

Get the Mx1 array of the mass/charge ratios of each position

property mass_extents: Tuple[float, float]

Get the min and max detected mass/charge ratio

mass_histogram(bin_width=0.05, lower=0, upper=200, multiplicity='all', norm=False)

Get the mass/charge ratio histogram of the given Roi. This function is cached to increase speed under repeated calls.

Parameters:

• bin_width (Number) – Bin width in daltons

• lower (Number) – Minimum mass/charge ratio

• upper (Number) – Minimum mass/charge ratio

• multiplicity (Union[str, int]) – The portion of multiplicity to generate the histogram from. “All” for all hits, int >= 1 for a specific multiplicity, “multiples” for all multiple hits.

• norm (Union[bool, Tuple[Number, Number]]) – Normalize the histogram to unity. True/False to generate normalization constant from the whole spectrum, or Tuple[float, float] to generate normalization constant from a range on the spectrum.

Return type:

(ndarray, ndarray)

memory_size()

Get the approximate memory footprint in Mb

Return type:

float

property misc: dict

Get the dictionary of miscellaneous data for each position. This is usually populated automatically when the Roi is create from Roi.from_epos() or Roi.from_ato().

property multiplicities: ndarray

Get an array of the sorted multiplicities.

multiplicity_counts()

Get the statistical count of each degree of multiple-detector events

Return type:

Tuple[ndarray, ndarray]

multiplicity_fraction()

Get the statistical fraction of each degree of multiple-detector events

Return type:

Tuple[ndarray, ndarray]

multiplicity_percentage()

Get the statistical percentage of each degree of multiple-detector events

Return type:

Tuple[ndarray, ndarray]

plot_mass_spectrum()

Get an interactive plot of the mass spectrum of the Roi.

require_detector_info()

Use when a function/argument requires detector information

require_multihit_info()

Use when a function/argument requires multiple hit information

require_tof_info()

Use when a function/argument requires time of flight information

to_epos(filepath)

Write the roi to a standard extended pos file

Parameters:

filepath (str) – path of the epos file

to_pos(filepath)

Write the roi to a standard pos file

Parameters:

filepath (str) – path of the pos file

tof_histogram(bin_width=1, multiplicity='all', norm=False, cutoff=2000)

Get the time-of-flight histogram of the given Roi. This function is cached to increase speed under repeated calls.

Parameters:

• bin_width (Number) – Bin width in Da

• multiplicity (Union[str, int]) – The portion of multiplicity to generate the histogram from. “All” for all hits, int >= 1 for a specific multiplicity, “multiples” for all multiple hits.

• norm (Union[bool, Tuple[Number, Number]]) – Normalize the histogram to unity. True/False to generate normalization constant from the whole spectrum, or Tuple[float, float] to generate normalization constant from a range on the spectrum.

• cutoff (float) – Maximum time of flight value to generate the histogram

Return type:

(ndarray, ndarray)

property xyz: ndarray

Get the Mx3 array of the x/y/z positions

property xyz_center: ndarray

Get the center of all positions as the mean of all x/y/z values

property xyz_extents: Tuple[Tuple[float, float], ...]

Get the min/max spatial values of the x/y/z coordinates in nm.

RoiCylinder

class apav.RoiCylinder(parent, center, radius, height, axis='z')

Creates a new roi from an existing roi, containing ions within a cylinder

Parameters:

• parent (Roi) – Parent Roi to generate the subset from

• center (Tuple[Number, Number, Number]) – Geometric center to place the cylinder

• radius (Number) – Radius of the cylinder

• height (Number) – Height of the cylinder

• axis (str) – Axis to orient the cylinder. Either “x”, “y”, or “z”

RoiSphere

class apav.RoiSphere(parent, center, radius)

Creates a new roi from an existing roi, containing ions within a sphere

Parameters:

• parent (Roi) – Parent Roi to generate the subset from

• center (Tuple[Number, Number, Number]) – Geometric center of the sphere

• radius (Number) – Radius of the sphere

RoiRectPrism

class apav.RoiRectPrism(parent, center, widths)

Creates a new roi from an existing roi, containing ions within a rectangular prism

Parameters:

• parent (Roi) – Parent Roi to generate the subset from

• center (Tuple[Number, Number, Number]) – Geometric center to place the rectangular prism

• widths (Tuple[Number, Number, Number]) – x, y, z lengths of the rectangular prism