Spectrum

The position of spectra is not yet completely set in ixdat.

A spectrum is in essence just a 1-D field where a response variable (e.g. counts, detector current, adsorption) lives on a space defined by a scanning variable (e.g. wavelength, mass-to-charge ratio, two-theta). As such it could be a DataSeries on par with ValueSeries (a 1-D field with a value living in a space defined by a TimeSeries). A Spectrum is however a stand-alone output of an experimental technique. It could also be a type of Measurement.

As it is now, Spectrum is its own base class on par with Measurement, with its own table (i.e. the Spectrum class inherits directly from Saveable). It has properties which give quick access to the scanning variable and response as x and y, respectively. It also has its own plotter and exporter.

Similar questions can be raised about a sequence of spectra - whether it is a Measurement or a 2-D field. As it is now, sequences of spectra are represented by SpectrumSeries, which inherits from Spectrum.

The spectra module

Base classes for spectra and spectrum series

Note on grammar:

The spectrum class corresponds to a database table which we call “spectrums”. This is an intentional misspelling of the plural of “spectrum”. The correctly spelled plural, “spectra”, is reserved for a Field wrapping a 2-D array, each row of which is the y values of a spectrum. This use of two plurals of “spectrum” is analogous to the use of “persons” and “people” as distinct plurals of the word “person”. While “persons” implies that each person referred to should be considered individually, “people” can be considered as a group.

class ixdat.spectra.MultiSpectrum(*, name, technique=None, tstamp=None, sample_name=None, metadata=None, fields=None, field_ids=None)

The MultiSpectrum class.

A collection of spectra having the same x values and tstamp. The y values of the spectra in a MultiSpectrum can describe the same kind of thing, such as in the multiple scans of an XPS measurement, where the average of the spectra is the most-used quantity; or can different things, like fluorescence and transmission measured simultaneously while varying the incident x-ray energy on a beamline.

Indexing with a spectrum name returns a Spectrum object with that thing, or a smaller MultiSpectrum if there are multiple spectra with that name.

property fields

Make sure Fields are loaded and have the same xseries

classmethod from_spectrum_list(spectrum_list, technique=None, metadata=None, sample_name=None)

Build a MultiSpectrum from a list of Spectrums

property spectrum_list

The spectra of the multi-spectrum as a list of Spectrum objects.

property xseries

The shared xseries of all the spectra in the multi-spectrum

class ixdat.spectra.SpectroMeasurement(*args, spectrum_series=None, spectrum_id=None, **kwargs)

cut(tspan, t_zero=None)

Select the portion of the data in a given tspan.

See cut()

set_spectrum_series(spectrum_series)

(Re-)set the spectrum_series to a provided spectrum_series

property spectra

The field of the SpectrumSeries. spectra.data is a 2-D array

property spectrum_id

The id of the SpectrumSeries

property spectrum_series

The SpectrumSeries with the spectral data

property tstamp

The unix epoch time used by the measurement as t=0

Type

Float

class ixdat.spectra.Spectrum(*, name, technique='spectrum', metadata=None, sample_name=None, reader=None, tstamp=None, field=None, field_id=None, duration=None)

The Spectrum class.

A spectrum is a data structure including one-dimensional arrays of x and y variables of equal length. Typically, information about the state of a sample can be obtained from a plot of y (e.g. absorbtion OR intensity OR counts) vs x (e.g energy OR wavelength OR angle OR mass-to-charge ratio). Even though in reality it takes time to require a spectrum, a spectrum is considered to represent one instance in time.

In ixdat, the data of a spectrum is organized into a 1-Dimensional Field, where the y-data is considered to span a space defined by the x-data.

The Spectrum class makes the data in this field intuitively available. If spec is a spectrum, spec.x and spec.y give access to the x and y data, respectively, while spec.xseries and spec.yseries give the corresponding DataSeries.

property data_objects

The data-containing objects that need to be saved when the spectrum is saved.

For a field to be correctly saved and loaded, its axes_series must be saved first. So there are three series in the data_objects to return FIXME: with backend-specifying id’s, field could check for itself whether FIXME: its axes_series are already in the database.

property field

Since a spectrum can be loaded lazily, we make sure the field is loaded

property field_id

The id of the field

classmethod from_data(x, y, tstamp=None, x_name='x', y_name='y', x_unit_name=None, y_unit_name=None, **kwargs)

Initiate a spectrum from data. Does so via cls.from_series

Parameters

• x (np array) – x data

• y (np array) – y data

• tstamp (timestamp) – The timestamp of the spectrum. Defaults to None.

• x_name (str) – Name of the x variable. Defaults to ‘x’

• y_name (str) – Name of the y variable. Defaults to ‘y’

• x_unit_name (str) – Name of the x unit. Defaults to None

• y_unit_name (str) – Name of the y unit. Defaults to None

• kwargs – Key-word arguments are passed on ultimately to cls.__init__

classmethod from_field(field, **kwargs)

Initiate a spectrum from data. Does so via cls.from_field

Parameters

• field (Field) – The field containing all the data of the spectrum. field.data is the y-data, which is considered to span x and t. field.axes_series[0] is a DataSeries with the x data. field.axes_series[1] is a TimeSeries with one time point.

• kwargs – key-word arguments are passed on ultimately to cls.__init__

classmethod from_series(xseries, yseries, tstamp, **kwargs)

Initiate a spectrum from data. Does so via cls.from_field

Parameters

• xseries (DataSeries) – A series with the x data

• yseries (DataSeries) – A series with the y data. The y data should be a vector of the same length as the x data.

• tstamp (timestamp) – The timestamp of the spectrum. Defaults to None.

• kwargs – Key-word arguments are passed on ultimately to cls.__init__

classmethod read(path_to_file, reader, **kwargs)

Return a Measurement object from parsing a file with the specified reader

Parameters

• path_to_file (Path or str) – The path to the file to read

• reader (str or Reader class) – The (name of the) reader to read the file with.

• kwargs – key-word arguments are passed on to the reader’s read() method.

classmethod read_set(path_to_file_start=None, part=None, suffix=None, file_list=None, reader=None, **kwargs)

Read a set of spectrum files and append them to return SpectrumSeries

Note: The list of spectrums is sorted by time.

Parameters

• path_to_file_start (Path or str) – The path to the files to read including the shared start of the file name: Path(path_to_file).parent is interpreted as the folder where the file are. Path(path_to_file).name is interpreted as the shared start of the files to be appended.

• part (Path or str) – A path where the folder is the folder containing data and the name is a part of the name of each of the files to be read and combined.

• suffix (str) – If a suffix is given, only files with the specified ending are added to the file list

• file_list (list of Path) – As an alternative to path_to_file_start or part, the exact files to append can be specified in a list

• reader (str or Reader class) – The (name of the) reader to read the files with

• kwargs – Key-word arguments are passed via cls.read() to the reader’s read() method, AND to SpectrumSeries.from_spectrum_list()

property series_list

A Spectrum’s series list includes its field and its axes_series.

property tseries

The TimeSeries of a spectrum is a single point [0] and its tstamp

property x

The x data is the data attribute of the xseries

property x_name

The name of the x variable is the name attribute of the xseries

property xseries

The x DataSeries is the first axis of the field

property y

The y data is the one-dimensional data attribute of the field

property y_name

The name of the y variable is the name attribute of the field

property yseries

The yseries is a DataSeries reduction of the field

class ixdat.spectra.SpectrumSeries(*args, **kwargs)

The SpectrumSeries class.

A spectrum series is a data structure including a two-dimensional array, each row of which is a spectrum, and each column of which is one spot in the spectrum as it changes with some other variable.

In ixdat, the data of a spectrum series is organized into a Field, where the y-data is considered to span a space defined by a DataSeries which is the x data, and a DataSeries (typically a TimeSeries) which enumerates or specifies when or under which conditions each spectrum was taken. The spectrum series will consider this its “time” variable even if it is not actually time.

The SpectrumSeries class makes the data in this field intuitively available. If spec is a spectrum series, spec.x is the x data with shape (N, ), spec.t is the time data with shape (M, ), and spec.y is the spectrum data with shape (M, N).

cut(tspan, t_zero=None)

Return a subset with the spectrums falling in a specified timespan

Parameters

• tspan (timespan) – The timespan within which you want spectrums

• t_zero (float) – The shift in t=0 with respect to the original spectrum series, in [s].

property field

Since a spectrum can be loaded lazily, we make sure the field is loaded

We also want to make sure that the field has the tstamp of the SpectrumSeries.

classmethod from_spectrum_list(spectrum_list, **kwargs)

Build a SpectrumSeries from a list of Spectrum objects.

property t

The time array of a SectrumSeries is the data of its tseries.

FIXME: It is the reader’s job to make sure that t is increasing,

i.e. that the spectra are sorted by time.

property t_name

The name of the time variable of the spectrum series

property tseries

The TimeSeries of a SectrumSeries is the 0’th axis of its field. Note that its data is not sorted!

property x

The x (scanning variable) data

property x_name

The name of the scanning variable

property xseries

The x-axis DataSeries of a SectrumSeries is the 1’st axis of its field

property y

The y data is the multi-dimensional data attribute of the field

property y_average

The y-data of the average spectrum

property yseries

The yseries is a DataSeries reduction of the field

ixdat.spectra.add_spectrum_series_to_measurement(measurement, spectrum_series, **kwargs)

Add a measurement and a spectrum measurement.

Parameters

• measurement (Measurement) – The Measurement object containing the time-resolved scalar values.

• spectrum_series (SpectrumSeries) – The SpectrumSeries object containing the 2-D time-resolved spectral data.

• kwargs – Additional key-word arguments are passed on to the from_dict constructor of the resulting object.

Returns SpectroMeasurement: The addition results in an object of SpectroMeasurement

or a subclass thereof if ixdat supports the hyphenated technique. For example, addition of an ECMeasurement and an XAS SpectrumSeries results in an ECXASMeasurement object.