pyHMSA is a pure Python implementation of the MSA / MAS / AMAS HyperDimensional Data File (HMSA, for short) specifications. This file format is intended to be a common exchange format for microscopy and microanalysis data. More information about the file format and its specifications can be found here.
The library is designed to be minimalist, leaving post-processing of the data to the user’s script. The only dependency of pyHMSA is to NumPy, in order to represent the multi-dimensional data.
pyHMSA is written to support both Python 2 and 3.
The library is provided under the MIT License.
pyHMSA was developed as part of the doctorate thesis project of Philippe T. Pinard at RWTH Aachen University (Aachen, Germany) under the supervision of Dr. Silvia Richter.
A few examples from the pyHMSA library.
This example shows how to create a new data file object from scratch and add one condition and one data set.
First, we import the DataFile class and define a datafile object:
from pyhmsa.datafile import DataFile
datafile = DataFile()
From the datafile object, the header can be modified using the attribute header, conditions can be added/modified/removed using the conditions which acts as a Python’s dictionary and data sets can be added/modified/removed in the same way as conditions using the data.
Let’s personalize the data file and specify values from some of the default header fields. The default header fields are: title, author, owner, date, time, timezone and checksum. The checksum field is automatically determined when saving a data file. The default header fields can be set using their respective attributes or using lowercase keys. The instance setting the title as follows:
datafile.header.title = 'Example'
is equivalent to this:
datafile.header['title'] = 'Example'
The date field of the header is stored as a datetime.date object as specified in Python’s standard library. The same goes for the time, stored as a datetime.time object. For more information on these objects, refer to Python’s standard library. For a new data file, the date and time will often correspond to the current date and time. A shortcut to set both is to use Python’s datetime.datetime object.
import datetime
datafile.header.datetime = datetime.datetime.now()
The next step is to create a condition. For this example, we will create an acquisition point condition (AcquisitionPoint). This condition requires to define a position. Positions are specified by the SpecimenPosition class. Note that per the HMSA specification, the specimen position could also be a condition on its own. All arguments of the specimen position are optional. We will define x, y and z.
from pyhmsa.spec.condition.specimenposition import SpecimenPosition
position = SpecimenPosition(x=0.0, y=1.0, z=2.0)
With this position we can create our acquisition condition object. The optional arguments (dwell_time, total_time, dwell_time_live) can be defined later.
from pyhmsa.spec.condition.acquisition import AcquisitionPoint
acq = AcquisitionPoint(position=position)
Numerical attributes with a magnitude (i.e. unit) can be defined in three different ways:
Using the set method and specify the unit as the second argument.
acq.set_dwell_time(5.0, 's')Using directly the attribute and a 2-item tuple where the first item is the value and the second the unit.
acq.dwell_time = (5.0, 's')Not specifying the unit. The default unit will be used. Refer to the documentation to know which unit is assigned by default.
acq.dwell_time = 5.0
Note that regardless how a numerical attribute is set, all get methods will return a special object called arrayunit. The details of this object is not important for the users, except that it behaves as a regular number (i.e. Python’s float) and that it has an extra attribute unit to retrieve the unit. For example,
print(acq.dwell_time) # Returns: 5.0 s
print(acq.get_dwell_time()) # Returns: 5.0 s
print(acq.dwell_time.unit) # Returns: s
Finally, we can add our acquisition point condition to the datafile object. We use the identifier Acq0.
datafile.conditions['Acq0'] = acq
All data set classes are derived from NumPy’s arrays. NumPy is a powerful Python library to handle multi-dimensional arrays. It also allows to define the type of data (integer, float) and the number of bytes. Based on the HMSA specifications the following NumPy data types are allowed: uint8, int16, uint16, int32, uint32, int64, float32 and float64. If you want to perform advanced array manipulation, we refer you to the NumPy’s documentation.
For this example, we will create a 1D analysis data set (Analysis1D). This data set is designed to store a measurement at a single point in space or time with one datum dimension. It has no collection dimensions. An example of such data set would be an EDS spectrum.
We create the data set with 1000 channels using the int64 data type.
import numpy as np
from pyhmsa.spec.datum.analysis import Analysis1D
channels = 1000
datum = Analysis1D(channels, np.int64)
At this point, the data set does not contain any values. No assumption can be made on the initial values. For the purpose of this example, we will fill the array using random numbers generated from 0 to 5000.
import random
datum[:] = [random.randint(0, 5000) for _ in range(channels)]
As for the condition, we add the new data set to the datafile object.
datafile.data['Spectrum0'] = datum
Now our data file is created, we obviously would like to save it. The datafile object was an easy utility method write which allows to save the object to disk. The method takes one argument, the location (absolute or relative) where to save the data file. Note that the extension of the file can either be .xml or .hmsa. Both files will automatically be created as per the HMSA specifications.
datafile.write('example1.xml')
Once a datafile object has been saved, it can be saved again to the same location by just calling write() without any argument.
datafile.write() # Save to the same location
#!/usr/bin/env python
from pyhmsa.datafile import DataFile
datafile = DataFile()
# Header
datafile.header.title = 'Example'
datafile.header['title'] = 'Example'
import datetime
datafile.header.datetime = datetime.datetime.now()
# Condition
## Create a position
from pyhmsa.spec.condition.specimenposition import SpecimenPosition
position = SpecimenPosition(x=0.0, y=1.0, z=2.0)
## Create an acquisition condition
from pyhmsa.spec.condition.acquisition import AcquisitionPoint
acq = AcquisitionPoint(position=position)
acq.set_dwell_time(5.0, 's')
acq.dwell_time = (5.0, 's')
acq.dwell_time = 5.0
print(acq.dwell_time) # Returns: 5.0 s
print(acq.get_dwell_time()) # Returns: 5.0 s
print(acq.dwell_time.unit) # Returns: s
## Add condition to datafile with the ID = Acq0
datafile.conditions['Acq0'] = acq
# Dataset
## Create a dataset (NumPy array) of 1000 64-bit integers
import numpy as np
from pyhmsa.spec.datum.analysis import Analysis1D
channels = 1000
datum = Analysis1D(channels, np.int64)
## Assign values to the array by generating a random integer between 0 and 5000
import random
datum[:] = [random.randint(0, 5000) for _ in range(channels)]
## Add dataset to datafile with the ID = Spectrum0
datafile.data['Spectrum0'] = datum
# Save datafile to a file
## Only one of the two files need to be specified, either .xml or .hmsa
datafile.write('example1.xml')
datafile.write() # Save to the same location
In this example, we will read one of the example HMSA data files provided by the authors: Brecci EDS spectrum. You can download the data file here.
We first import the DataFile class.
from pyhmsa.datafile import DataFile
Then assuming that the Breccia EDS spectrum files are in the same folder as this script, we simply called the class method read.
datafile = DataFile.read('Breccia - EDS sum spectrum.xml')
And that’s all!
Reading a large data file may take a long time since all the information is transfered in the memory. To get a progress report or to prevent blocking operation, the pyHMSA API provides an advanced reader DataFileReader which operates inside a thread. It can be used as follows:
import time
from pyhmsa.fileformat.datafile import DataFileReader
reader = DataFileReader()
reader.read('Breccia - EDS sum spectrum.xml')
while reader.is_alive():
print('{0:n}% - {1}'.format(reader.progress * 100.0, reader.status))
time.sleep(0.1)
print('{0:n}% - {1}'.format(reader.progress * 100.0, reader.status))
Note that the read only initiates the reading process, but does not any data file. The method get must be called to return the data file.
#!/usr/bin/env python
from pyhmsa.datafile import DataFile
datafile = DataFile.read('Breccia - EDS sum spectrum.xml')
# Advanced
import time
from pyhmsa.fileformat.datafile import DataFileReader
reader = DataFileReader()
reader.read('Breccia - EDS sum spectrum.xml')
while reader.is_alive():
print('{0:n}% - {1}'.format(reader.progress * 100.0, reader.status))
time.sleep(0.1)
print('{0:n}% - {1}'.format(reader.progress * 100.0, reader.status))
datafile = reader.get()
In the first example, we create an acquisition point condition, but only added it to the conditions inside the data file object. Conditions can also be, and in many cases, should be associated directly with the data set(s) they are representing. It is often the case that the same condition is shared between several data sets. For instance, the condition describing the instrument (Instrument) is usually applicable to all collected data sets. So, how to add conditions to data sets?
Let’s assume we have a data set named datum and a condition named acq (as in the first example):
# Condition
from pyhmsa.spec.condition.specimenposition import SpecimenPosition
from pyhmsa.spec.condition.acquisition import AcquisitionPoint
position = SpecimenPosition(x=0.0, y=1.0, z=2.0)
acq = AcquisitionPoint(position=position)
acq.set_dwell_time(5.0, 's')
# Dataset
import random
import numpy as np
from pyhmsa.spec.datum.analysis import Analysis1D
channels = 1000
datum = Analysis1D(channels, np.int64)
datum[:] = [random.randint(0, 5000) for _ in range(channels)]
In the current state, the data set nor the condition are added to the data file object. Each data set object has a conditions attribute that acts exactly as the conditions attribute of the DataFile object. We can then simply add the condition as we did before.
datum.conditions['Acq0'] = acq
Now let’s add the datum to the data file object.
datafile.data['Spectrum'] = datum
That’s all, but there is some magic that also happened when adding the data set to the data file object. If we list the data file’s conditions, we will see that our condition, added to the data set, is also present.
print(list(datafile.conditions)) # Returns: ['Acq0']
The conditions attribute of the data file object contains all conditions of the whole data file object. We can technically retrieve and modified the same condition from two locations: the data file or the data set.
assert datafile.conditions['Acq0'] is datafile.data['Spectrum'].conditions['Acq0']
Note that the order of the operation is not important. The conditions added to a data set will always be added to the overall conditions of the data file.
Some precisions must be made regarding removing conditions. If a condition is removed from the data file, it will also be removed from all data sets having this condition.
del datafile.conditions['Acq0']
print(list(datafile.conditions)) # Returns: []
print(list(datafile.data['Spectrum'].conditions)) # Returns: []
However, if a condition is removed from a data set, it will only be removed from this data set and not from the data file.
datafile.data['Spectrum'].conditions['Acq0'] = acq # Reset
del datafile.data['Spectrum'].conditions['Acq0']
print(list(datafile.conditions)) # Returns: ['Acq0']
print(list(datafile.data['Spectrum'].conditions)) # Returns: []
This behavior may appear counter-intuiative but it is not possible to know if that condition was added first to a data set or directly to the data file’s conditions.
#!/usr/bin/env python
from pyhmsa.datafile import DataFile
datafile = DataFile()
# Condition
from pyhmsa.spec.condition.specimenposition import SpecimenPosition
from pyhmsa.spec.condition.acquisition import AcquisitionPoint
position = SpecimenPosition(x=0.0, y=1.0, z=2.0)
acq = AcquisitionPoint(position=position)
acq.set_dwell_time(5.0, 's')
# Dataset
import random
import numpy as np
from pyhmsa.spec.datum.analysis import Analysis1D
channels = 1000
datum = Analysis1D(channels, np.int64)
datum[:] = [random.randint(0, 5000) for _ in range(channels)]
# Assign condition
datum.conditions['Acq0'] = acq
# Add dataset
datafile.data['Spectrum'] = datum
# Check
print(list(datafile.conditions)) # Returns: ['Acq0']
assert datafile.conditions['Acq0'] is datafile.data['Spectrum'].conditions['Acq0']
# Removing globally
del datafile.conditions['Acq0']
print(list(datafile.conditions)) # Returns: []
print(list(datafile.data['Spectrum'].conditions)) # Returns: []
# Removing locally
datafile.data['Spectrum'].conditions['Acq0'] = acq # Reset
del datafile.data['Spectrum'].conditions['Acq0']
print(list(datafile.conditions)) # Returns: ['Acq0']
print(list(datafile.data['Spectrum'].conditions)) # Returns: []
We show in this example how to extract a spectrum from a HMSA data file and save it in a CSV file with Python. As in the second example, we use one of the example HMSA data files provided by the authors: Brecci EDS spectrum. You can download the data file here.
First, let’s read the data file.
from pyhmsa.datafile import DataFile
datafile = DataFile.read('Breccia - EDS sum spectrum.xml')
Then, we must find the data set corresponding to our spectrum. In this case, the data set is called EDS sum spectrum so we could retrieve it from its ID.
spectrum = datafile.data['EDS sum spectrum']
However, in some cases, we might not know the name of a data set or an only a portion of the name. The library offers search methods to find both data sets and conditions.
For instance, we could search for all data sets containing the word spectrum as follow:
results = datafile.data.findvalues('*spectrum*')
print(len(results)) # Returns: 1
The * in the search pattern are wild cards and indicates to match any character.
We could also search based on the type of data set. In this case, we are looking for an Analysis1D data set.
from pyhmsa.spec.datum.analysis import Analysis1D
results = datafile.data.findvalues(Analysis1D)
print(len(results)) # Returns: 1
Once we have our data set, we can use the utility method get_xy to retrieve a two-dimensional array where the first column contains x values and the second y values. This method is particularly useful since it will search through the associated conditions to the data set to see if a calibration was defined for the x values. In this example, a linear calibration with an offset of -237.098251 was defined. The first x value should therefore be equal to this value.
spectrum = next(iter(results)) # Take first result
xy = spectrum.get_xy()
print(xy[0, 0]) # Returns -237.098251
The get_xy can also returns labels for the x and y values as defined in the conditions.
xlabel, ylabel, xy = spectrum.get_xy(with_labels=True)
Finally, we can use Python’s csv module to create the CSV file.
import csv
with open('breccia.csv', 'w') as fp:
writer = csv.writer(fp) # Create CSV writer
writer.writerow([xlabel, ylabel]) # Header
writer.writerows(xy)
#!/usr/bin/env python
from pyhmsa.datafile import DataFile
datafile = DataFile.read('Breccia - EDS sum spectrum.xml')
spectrum = datafile.data['EDS sum spectrum']
# Search
results = datafile.data.findvalues('*spectrum*')
print(len(results)) # Returns: 1
from pyhmsa.spec.datum.analysis import Analysis1D
results = datafile.data.findvalues(Analysis1D)
print(len(results)) # Returns: 1
spectrum = next(iter(results)) # Take first result
xy = spectrum.get_xy()
print(xy[0, 0]) # Returns -237.098251
xlabel, ylabel, xy = spectrum.get_xy(with_labels=True)
# Save
import csv
with open('breccia.csv', 'w') as fp:
writer = csv.writer(fp) # Create CSV writer
writer.writerow([xlabel, ylabel]) # Header
writer.writerows(xy)
Although ASCII characters are preferred throughout the HMSA specifications, it is possible to provide information in Unicode character and alternative spelling.
In pyHMSA, this is done through a special object type called langstr. This object behaves exactly like the default Python’s str type with the exception that alternative spelling can be provided. Let’s look at an example how to specify an author’s name in two different languages.
First we create a data file object and import the langstr type.
from pyhmsa.datafile import DataFile
from pyhmsa.type.language import langstr
datafile = DataFile()
Then we create a new langstr object for the author’s name. The first argument of langstr is the name in English (i.e. ASCII characters). The second argument is a dictionary where the key is a valid language code and/or country code, as specified by ISO 639-1 and ISO 3166, respectively.
author = langstr('Wilhelm Conrad Roentgen', {'de': u'Wilhelm Conrad Röntgen'})
datafile.header.author = author
The alternative spellings of a string can be access using the attribute alternatives which returns a dictionary. Note that once created a langstr object is immutable; it cannot be modified.
print(datafile.header.author.alternatives['de']) # Returns ...
#!/usr/bin/env python
from pyhmsa.datafile import DataFile
from pyhmsa.type.language import langstr
datafile = DataFile()
author = langstr('Wilhelm Conrad Roentgen', {'de': u'Wilhelm Conrad Röntgen'})
datafile.header.author = author
print(datafile.header.author.alternatives['de']) # Returns ...
Specifying the x-ray line in an ElementalIDXray condition is slightly different than other attributes, so this example shows how to do it. In microanalysis, there exists two common types of nomenclature for x-ray line: the one proposed by the IUPAC (e.g. K-L3) and the traditional Siegbahn notation (Ka1). HMSA specifications does not enforce one notation over the other and encourage the users to specify the x-ray line in both notations.
In a similar way as for alternative languages (see the example on Use alternative language), a new type is defined for x-ray lines: xrayline. The type takes two required arguments (the x-ray line and its notation) and an optional argument for the x-ray line express in the other notation. For example, we can specify the Ka1 line as follows:
from pyhmsa.type.xrayline import xrayline, NOTATION_SIEGBAHN
line = xrayline('Ka1', NOTATION_SIEGBAHN, 'K-L3')
The alternative value is automatically interpreted to be expressed in the IUPAC notation.
This new line object can then be used to create a new ElementalIDXray condition.
from pyhmsa.spec.condition.elementalid import ElementalIDXray
condition = ElementalIDXray(29, line, (8047.82, 'eV'))
print(condition) # Returns: <ElementalIDXray(atomic_number=29, energy=8047.82 eV, line=Ka1)>
#!/usr/bin/env python
from pyhmsa.type.xrayline import xrayline, NOTATION_SIEGBAHN
line = xrayline('Ka1', NOTATION_SIEGBAHN, 'K-L3')
from pyhmsa.spec.condition.elementalid import ElementalIDXray
condition = ElementalIDXray(29, line, (8047.82, 'eV'))
print(condition) # Returns: <ElementalIDXray(atomic_number=29, energy=8047.82 eV, line=Ka1)>
The API follows closely the name convention, hierarchy and parameter names of the HMSA specifications. The type of conditions and datasets available can be found below.
List of available conditions:
Conditions containing the parameters used for the acquisition of the data.
Defines the position and duration for a singular measurement of the specimen.
| Parameters: |
|
|---|
uniform real time taken for each individual measurement
analogous detector live time for each individual measurement
physical location on (or in) the specimen
total real time taken to collect all measurements
Defines the position and duration of an irregular sequence of measurements of the specimen.
| Parameters: |
|
|---|
uniform real time taken for each individual measurement
analogous detector live time for each individual measurement
specimen positions
total real time taken to collect all measurements
Defines the position and duration of a one-dimensional raster over the specimen. Applies only to a linear sequence of steps, using equal step sizes and dwell times for each measurement. For irregular step sizes, refer to AcquisitionMultiPoint
| Parameters: |
|
|---|
uniform real time taken for each individual measurement
analogous detector live time for each individual measurement
number of accumulated frames
Returns the end position.
| Returns: | end position |
|---|---|
| Return type: | SpecimenPosition |
Returns the start position.
| Returns: | start position |
|---|---|
| Return type: | SpecimenPosition |
End position
Start position
defined physical location(s) of the raster
mode of rastering
Sets the end position.
| Parameters: | value (SpecimenPosition) – end position |
|---|
Sets the start position.
| Parameters: | value (SpecimenPosition) – start position |
|---|
number of steps
dimension of each step
total real time taken to collect all measurements
Defines the position and duration of a two-dimensional X/Y raster over the specimen.
| Parameters: |
|
|---|
uniform real time taken for each individual measurement
analogous detector live time for each individual measurement
number of accumulated frames
Returns the physical location on (or in) the specimen.
| Returns: | specimen position |
|---|---|
| Return type: | SpecimenPosition |
Physical location on (or in) the specimen
defined physical location(s) of the raster
mode of rastering
Sets the physical location on (or in) the specimen.
| Parameters: |
|
|---|
number of steps in x direction
number of steps in y direction
dimension of each step in x direction
dimension of each step in y direction
total real time taken to collect all measurements
Defines the position and duration of a three-dimensional X/Y/Z raster over the specimen.
| Parameters: |
|
|---|
uniform real time taken for each individual measurement
analogous detector live time for each individual measurement
Returns the physical location on (or in) the specimen.
| Returns: | specimen position |
|---|---|
| Return type: | SpecimenPosition |
Physical location on (or in) the specimen
defined physical location(s) of the raster
mode of rastering
mode of rastering in z direction
Sets the physical location on (or in) the specimen.
| Parameters: |
|
|---|
number of steps in x direction
number of steps in y direction
number of steps in z direction
dimension of each step in x direction
dimension of each step in y direction
dimension of each step in z direction
total real time taken to collect all measurements
Conditions describing the composition of a material.
Defines the composition of a material in terms of its constituent elements. The composition is a dict where the keys are atomic numbers and the values the amounts of an element.
| Parameters: | unit – unit in which the composition is defined (required) |
|---|
If key is not found, d is returned if given, otherwise KeyError is raised.
as a 2-tuple; but raise KeyError if D is empty.
Returns a CompositionElemental with unit of wt%.
unit in which the composition is defined
If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
Conditions describing the type and configuration of a detector used to collect the data.
Defines the energy/wavelength/etc calibration of a spectrometer or other measurement device operating at a fixed position, such as a CL monochromator.
| Parameters: |
|
|---|
physical quantity
unit
constant value
Defines the energy/wavelength/etc calibration of a spectrometer or other measurement device, for which the measurement ordinals (e.g. channel numbers) have a linear relationship to the physical quantity (e.g. nm), with a constant offset and gain.
| Parameters: |
|
|---|
gain
offset
physical quantity
unit
Defines the energy/wavelength/etc calibration of a spectrometer or other measurement device, for which the measurement ordinals (e.g. channel numbers) have a relationship to the physical quantity (e.g. nm) that may be modelled by an nth order polynomial.
| Parameters: |
|
|---|
polynomial coefficients
physical quantity
unit
Defines the energy/wavelength/etc calibration of a spectrometer or other measurement device, for which relationship between the measurement ordinals (e.g. channel numbers) and physical quantity (e.g. nm) cannot be adequately modelled by linear or polynomial functions, and therefore must be declared explicitly for each ordinal as an array of floating point values.
| Parameters: |
|
|---|
text labels for each of the calibration points
physical quantity
unit
explicit values
Defines a layer of a window.
| Parameters: |
|
|---|
material
thickness
Defines the layer(s) of a window.
| Parameters: | layers – iterable of Layer (optional) |
|---|
Helper function that creates a new Layer and appends it to this window.
| Parameters: |
|
|---|---|
| Returns: | created layer |
| Return type: | Layer |
modifiable list of layers
Defines the condition of the pulse height analyser of a WDS spectrometer.
| Parameters: |
|
|---|
base level
bias
gain
mode
window
Describes the calibration and collection mode of a camera used to collect a HMSA dataset, such as an EBSD or TEM camera. The camera detector is expected to have two datum axes (U and V) which are, in general, assumed to be independent of the specimen coordinate dimensions (X/Y/Z).
| Parameters: |
|
|---|
area
azimuth
distance
elevation
exposure time
focal length
magnification
manufacturer
measurement unit
model
number of pixels along the horizontal axis
number of pixels along the vertical axis
semi-angle
serial number
type of signal
solid angle
temperature
Describes the calibration and collection mode of a spectrometer used to collect a HMSA dataset.
| Parameters: |
|
|---|
area
azimuth
calibration
number of channels
mode of collection
distance
elevation
manufacturer
measurement unit
model
semi-angle
serial number
type of signal
solid angle
temperature
Describes the type and configuration of a cathodoluminescence spectrometer.
Note
If the spectrometer is operating as a monochromator (e.g. monochromatic CL mapping), the calibration definition shall be of type CalibrationConstant.
| Parameters: |
|
|---|
area
azimuth
calibration
number of channels
mode of collection
distance
elevation
grating spacing
manufacturer
measurement unit
model
semi-angle
serial number
type of signal
solid angle
temperature
Describes the type and configuration of a wavelength dispersive x-ray spectrometer.
Note
If the spectrometer is operating as a monochromator (e.g. WDS mapping), the calibration definition shall be of type CalibrationConstant.
| Parameters: |
|
|---|
area
azimuth
calibration
number of channels
mode of collection
crystal 2d-spacing
dispersion element
distance
elevation
manufacturer
measurement unit
model
pulse height analyzer
Rowland circle diameter
semi-angle
serial number
type of signal
solid angle
temperature
window
Describes the type and configuration of an energy dispersive x-ray spectrometer.
| Parameters: |
|
|---|
area
azimuth
calibration
number of channels
mode of collection
distance
elevation
manufacturer
measurement unit
model
nominal throughput
semi-angle
serial number
type of signal
solid angle
strobe rate
technology
temperature
time constant
window
Conditions defining elemental identification.
Defines and elemental identification, as may be useful for region of interest images, XAFS spectral maps, and the like.
| Parameters: | z – atomic number (required) |
|---|
atomic number
Returns the symbol.
Symbol
Defines and elemental identification based on an x-ray peak, as may be useful for region of interest images and the like.
| Parameters: |
|
|---|
atomic number
energy of x-ray line
Returns the symbol.
x-ray line
Symbol
Conditions describing the type of instrument used to collect the data.
Describes the type of instrument used to collect a HMSA dataset.
| Parameters: |
|
|---|
manufacturer
model
serial number
Conditions describing the type and conditions of the analytical probe used to collect the data.
Describes the electron column conditions of the transmission electron microscope used to collect a HMSA dataset.
| Parameters: |
|
|---|
beam current
beam diameter
beam voltage
chamber pressure
emission current
extractor bias
filament current
gun pressure
type of gun
scan magnficiation
working_distance
Describes the electron column conditions of the transmission electron microscope used to collect a HMSA dataset.
| Parameters: |
|
|---|
beam current
beam diameter
beam voltage
camera magnification
chamber pressure
semi-angle of incident beam
emission current
extractor bias
filament current
gun pressure
type of gun
lens mode
scan magnficiation
working_distance
Conditions defining a region of spectrum.
Defines a region of a spectrum (or other one-dimensional datum), as may be useful for defining start and end channels used for a region of interest image.
| Parameters: |
|
|---|
Channel range
End channel
Returns the end channel.
Returns the start channel.
Start channel
Conditions defining a physical specimen.
Defines a layer of a multi-layered specimen.
| Parameters: |
|
|---|
composition
formula
Returns whether this layer is a bulk layer.
name
thickness
Defines a physical specimen, including the name, origin, composition, etc.
| Parameters: |
|
|---|
composition
description
formula
name
origin
temperature
Defines a multi-layered physical specimen
| Parameters: |
|
|---|
Utility function to create a layer.
| Parameters: |
|
|---|---|
| Returns: | created layer |
| Return type: |
composition
description
formula
modifiable list of layers
name
origin
temperature
Conditions definining a physical location on (or in) the specimen.
Defines a physical location on (or in) the specimen. The position shall be defined in the coordinate system of the instrument. This version of the HMSA standard does not specify a template or definition of coordinate systems.
| Parameters: |
|
|---|
rotation
tilt
x coordinate
y coordinate
z coordinate
List of available datasets:
Dataset used to store a single measurement of a specimen at a single point in space or time.
Data with 0 collection dimensions and 0 datum dimensions implies a dataset comprising of one single-valued measurement.
Dimensions and order of the collections
Conditions associated to this dataset.
Dimensions and order of the data.
Stores a measurement of a specimen at a single point in space or time with one datum dimension.
Dimensions and order of the collections
Conditions associated to this dataset.
Store a single measurement of the specimen at a single point in space or time with two datum dimensions, such as a diffraction pattern.
Note
This dataset type shall not be used to store 2 dimensional images rastered over the specimen, such as a conventional TEM or SEM image. Instead, such data shall be stored using the ImageRaster2D.
Dimensions and order of the collections
Conditions associated to this dataset.
Dataset used to store a sequence of point measurements collected under the same conditions, but in an irregular pattern (line scan, time sequence, sparsely scanned image).
Represents a sequence of point measurements with zero datum dimension, such as a line scan or time sequence of single-valued data (e.g. Ti counts, BSE yield, vacuum pressure).
Conditions associated to this dataset.
Dimensions and order of the data.
Dataset used to store rastered results over regularly spaced intervals in one or more dimensions, such as a 1D linescan, a 2D image or a 3D serial section.
Represents a dataset that has been raster mapped in 2D (x/y dimensions).
Conditions associated to this dataset.
Dimensions and order of the data.
Represents a dataset that has been raster mapped in 2D (x/y dimensions), where for each raster coordinate, the datum collected was a 1D array (channel dimension). An example of this type of dataset is a SEM-XEDS map.
Conditions associated to this dataset.
Represents a dataset that has been raster mapped in 2D (x/y dimensions), where for each raster coordinate, the datum collected was a 2D image (U/V dimensions.
Conditions associated to this dataset.
The main object of the library is the DataFile which regroups in a single object the Header, Conditions and datasets. HMSA files can be created, read and written from this object.
This is the main class to read, write and create HMSA data file.
Creates a new MSA hyper dimensional data file.
Conditions and data objects can be added using the attributes conditions and data, respectively. Note that conditions part of any datum object will also appear in the global conditions dictionary.
| Parameters: |
|
|---|
Conditions
Data
Path where the data file was last saved. Always .hmsa extension used.
Header
Language
Conditions that are not associated to any data sets (read-only).
Reads an existing MSA hyper dimensional data file and returns an object of this class.
| Parameters: | filepath – either the location of the XML or HMSA file. Note that both have to be present. |
|---|
Version
Writes this data file to disk.
| Parameters: | filepath – either the location of the XML or HMSA file |
|---|
Other classes of the library used to define data types, to read and write HMSA files as well as some utilities can be found here:
Check sum class and method to calculate.
Base class for conditions and data dictionaries.
Language type to deal with alternative spellings.
Special type to express magnitudes, values with a unit. It also implements the HMSA specifications restrictions on the types of data.
Generate a unique identifier id.
Parse and validate unit.
The source code of the library can be viewed/forked/downloaded on GitHub.
Copyright (c) 2014 Philippe Pinard
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.