orsopy.fileio package

The role of the fileio module is to enable the creation of and parsing from ORSO reduced data files. All public classes and functions in the fileio module are available directly from fileio without needing to specify a particular submodule.

The ORSO file format specification is available here.

class orsopy.fileio.Column(name, unit=None, physical_quantity=None, flag_is=None, comment=None)

Bases: Header

Information about a data column.

name: str

unit: Optional[str] = None

physical_quantity: Optional[str] = None

flag_is: Optional[List[str]] = None

yaml_representer(dumper)

comment: Optional[str] = None

class orsopy.fileio.ComplexValue(real, imag=None, unit=None, error=None, comment=None)

Bases: Header

A value or list of values with an optional unit.

real: float

imag: Optional[float] = None

unit: Optional[str] = None

error: Optional[ErrorValue] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns the complex value as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.DataSource(owner, experiment, sample, measurement, comment=None)

Bases: Header

The data_source object definition.

Parameters:

• owner (Person) – This refers to the actual owner of the data set, i.e. the main proposer or the person doing the measurement on a lab reflectometer.

• experiment (Experiment) – Details of the experimental.

• sample (Sample) – Sample information.

• measurement (Measurement) – Measurement specifics.

owner: Person

experiment: Experiment

sample: Sample

measurement: Measurement

comment: Optional[str] = None

class orsopy.fileio.ErrorColumn(error_of, error_type=None, value_is=None, distribution=None, comment=None)

Bases: Header

Information about a data column.

error_of: str

error_type: Optional[Literal['uncertainty', 'resolution']] = None

value_is: Optional[Literal['sigma', 'FWHM']] = None

distribution: Optional[Literal['gaussian', 'triangular', 'uniform', 'lorentzian']] = None

yaml_representer(dumper)

property name

A convenience property to allow programs to get a valid name attribute for any column.

property to_sigma

The multiplicative factor needed to convert a FWHM to sigma.

The conversion factors can be found in common statistics and experimental physics text books or derived manually solving the variance definition integral. (e.g. Dekking, Michel (2005). A modern introduction to probability and statistics : understanding why and how. Springer, London, UK:) Values and some references available on Wikipedia, too.

comment: Optional[str] = None

class orsopy.fileio.Experiment(title, instrument, start_date, probe, facility=None, proposalID=None, doi=None, comment=None)

Bases: Header

A definition of the experiment performed.

Parameters:

• title (str) – Proposal or project title.

• instrument (str) – Reflectometer identifier.

• start_date (datetime) – Start date for the experiment.

• probe (Literal['neutron', 'x-ray']) – Radiation probe, either 'neutron' or 'x-ray'.

• facility (Optional[str]) – Facility where the experiment was performed.

• proposalID (Optional[str]) – Identifier for experiment at a facility.

• doi (Optional[str]) – Digital object identifier for the experiment, possibly provided by the facility.

title: str

instrument: str

start_date: datetime

probe: Literal['neutron', 'x-ray']

facility: Optional[str] = None

proposalID: Optional[str] = None

doi: Optional[str] = None

comment: Optional[str] = None

class orsopy.fileio.File(file, timestamp=None, hash=None, comment=None)

Bases: Header

A file with file path and a last modified timestamp.

file: str

timestamp: Optional[datetime] = None

hash: Optional[ContentHash] = None

comment: Optional[str] = None

class orsopy.fileio.Header

Bases: object

The super class for all the items in the orso module.

classmethod from_dict(data_dict)

Create class from dictionary as is returned from yaml file reader.

If user-supplied attributes are provided, they are not passed to the constructor but applied after instance generation.

property user_data

classmethod empty()

Create an empty instance of this item containing all non-option attributes as None.

Return type:

Header

Returns:

Empty class.

static asdict(header)

Static method for to_dict().

Parameters:

header (Header) – Object to convert to dictionary.

Return type:

dict

Returns:

Dictionary result.

to_dict()

Produces a clean dictionary of the Header object, removing any optional attributes with the value None or default value.

Return type:

dict

Returns:

Cleaned dictionary.

to_yaml()

Return the yaml string for the Header item

Return type:

str

Returns:

Yaml string

yaml_representer(dumper)

yaml_representer_compact(dumper)

to_nexus(root=None, name=None)

Produces an HDF5 representation of the Header object, removing any optional attributes with the value None.

Returns:

HDF5 object

class orsopy.fileio.InstrumentSettings(incident_angle, wavelength, polarization=Polarization.unpolarized, configuration=None, comment=None)

Bases: Header

Settings associated with the instrumentation.

Parameters:

• incident_angle (Union[Value, ValueRange]) – Angle (range) of incidence.

• wavelength (Union[Value, ValueRange]) – Neutron/x-ray wavelength (range).

• polarization (Union[Polarization, ValueVector]) – Radiation polarization as one of 'unpolarized', 'p', 'm', 'pp', 'pm', 'mp', 'mm', or a orsopy.fileio.base.ValueVector.

• configuration (Optional[str]) – Description of the instreument configuration (full polarized/liquid surface/etc).

incident_angle: Union[Value, ValueRange]

wavelength: Union[Value, ValueRange]

polarization: Union[Polarization, ValueVector] = 'unpolarized'

configuration: Optional[str] = None

comment: Optional[str] = None

class orsopy.fileio.Measurement(instrument_settings, data_files, additional_files=None, scheme=None, comment=None)

Bases: Header

The measurement elements for the header.

Parameters:

• instrument_settings (InstrumentSettings) – Instrumentation details.

• data_files (List[Union[File, str]]) – Raw data files produced in the measurement.

• additional_files (Optional[List[Union[File, str]]]) – Raw reference files used in the reduction.

• scheme (Optional[Literal['angle- and energy-dispersive', 'angle-dispersive', 'energy-dispersive']]) – Measurement scheme (one of 'angle-dispersive', 'energy-dispersive'/'angle- and energy-dispersive').

instrument_settings: InstrumentSettings

data_files: List[Union[File, str]]

additional_files: Optional[List[Union[File, str]]] = None

scheme: Optional[Literal['angle- and energy-dispersive', 'angle-dispersive', 'energy-dispersive']] = None

comment: Optional[str] = None

class orsopy.fileio.Orso(data_source, reduction, columns, data_set=None, **user_data)

Bases: Header

The Orso object collects the necessary metadata.

Parameters:

• data_source (DataSource) – Information about the origin and ownership of the raw data.

• reduction (Reduction) – Details of the data reduction that has been performed. The content of this section should contain enough information to rerun the reduction.

• columns (List[Union[Column, ErrorColumn]]) – Information about the columns of data that will be contained in the file.

• data_set (Union[int, str, None]) – An identifier for the data set, i.e. if there is more than one data set in the object.

data_source: DataSource

reduction: Reduction

columns: List[Union[Column, ErrorColumn]]

data_set: Union[int, str, None] = None

classmethod empty()

Create an empty instance of the ORSO header with all non-optional attributes as None.

Return type:

Orso

Returns:

Empty Orso class, within minimum required columns

column_header()

An information string that explains what each of the columns in a dataset corresponds to.

Return type:

str

Returns:

Explanatory string.

from_difference(other_dict)

Constructs another Orso instance from self, and a dict containing updated header information.

Parameters:

other_dict (dict) – Contains updated header information.

Return type:

Orso

Returns:

A new Orso object constructed from self, and the updated header information.

to_difference(other)

A dictionary containing the difference in header information between two Orso objects.

Parameters:

other (Orso) – Other header to diff with.

Return type:

dict

Returns:

Dictionary of the header information difference.

to_dict()

Adds the user data to the returned dictionary.

comment: Optional[str] = None

class orsopy.fileio.OrsoDataset(info, data)

Bases: object

Parameters:

• info (Orso) – The header information for the reflectivity measurement

• data (Union[ndarray, Sequence[ndarray], Sequence[Sequence]]) – The numerical data associated with the reflectivity measurement. The data has shape (npnts, ncols).

Raises:

ValueError – When ncols != len(self.info.columns).

info: Orso

data: Union[ndarray, Sequence[ndarray], Sequence[Sequence]]

classmethod from_dict(data_dict)

header()

The header string for the ORSO file.

Return type:

str

Returns:

Header string.

diff_header(other)

Return a header string that only contains changes to other OrsoDataset ensure that data_set is the first entry.

Parameters:

other (OrsoDataset) – Other OrsoDataset to compare against.

Return type:

str

Returns:

Header string with only changes.

save(fname)

Save the OrsoDataset.

Parameters:

fname (Union[TextIO, str]) – The file name to save to.

class orsopy.fileio.Person(name, affiliation, contact=None, comment=None)

Bases: Header

Information about a person, including name, affiliation(s), and contact information.

name: str

affiliation: str

contact: Optional[str] = None

comment: Optional[str] = None

class orsopy.fileio.Polarization(value)

Bases: str, Enum

Polarization of the beam used for the reflectivity.

Neutrons: The first symbol indicates the magnetisation direction of the incident beam, the second symbol indicates the direction of the scattered beam. If either polarization or analysis are not employed the symbol is replaced by “o”.

X-rays: Uses the conventional names pi, sigma, left and right. In experiments with polarization analysis the incident and outgoing polarizations are separated with an underscore “_”.

unpolarized = 'unpolarized'

po = 'po'

mo = 'mo'

op = 'op'

om = 'om'

mm = 'mm'

mp = 'mp'

pm = 'pm'

pp = 'pp'

pi = 'pi'

sigma = 'sigma'

left = 'left'

right = 'right'

pi_pi = 'pi_pi'

sigma_sigma = 'sigma_sigma'

pi_sigma = 'pi_sigma'

sigma_pi = 'sigma_pi'

yaml_representer(dumper)

class orsopy.fileio.Reduction(software, timestamp=None, creator=None, corrections=None, computer=None, call=None, script=None, binary=None, comment=None)

Bases: Header

A description of the reduction that has been performed.

Parameters:

• software (Software) – Software used for reduction.

• timestamp (Optional[datetime]) – Datetime of reduced file creation.

• creator (Optional[Person]) – The person or routine who created the reduced file.

• corrections (Optional[List[str]]) – A list of the corrections that have been performed.

• computer (Optional[str]) – Name of the reduction machine.

• call (Optional[str]) – Command line call or similar.

• script (Optional[str]) – Path to reduction script or notebook.

• binary (Optional[str]) – Path to full reduction information file.

software: Software

timestamp: Optional[datetime] = None

creator: Optional[Person] = None

corrections: Optional[List[str]] = None

computer: Optional[str] = None

call: Optional[str] = None

script: Optional[str] = None

binary: Optional[str] = None

comment: Optional[str] = None

class orsopy.fileio.Sample(name, category=None, composition=None, description=None, size=None, environment=None, sample_parameters=None, model=None, comment=None)

Bases: Header

A description of the sample measured.

Parameters:

• name (str) – An identified for the individual sample or the subject and state being measured.

• category (Optional[str]) – Simple sample description, front (beam side) / back, each side should be one of 'solid/liquid', 'liquid/solid', 'gas/liquid', 'liquid/liquid', 'solid/gas', 'gas/solid'.

• composition (Optional[str]) – Notes on the nominal composition of the sample e.g. Si | SiO2 (20 angstrom) | Fe (200 angstrom) | air (beam side).

• description (Optional[str]) – Further details of the sample, e.g. size.

• size (Optional[ValueVector]) – Sample size in x, y, z direction, where z is parallel to the surface normal and x is along the beam direction (important for footprint correction).

• environment (Optional[List[str]]) – Name of the sample environment device(s).

• sample_parameters (Optional[Dict[str, Union[Value, ValueRange, ValueVector, ComplexValue, AlternatingField]]]) – Dictionary of sample parameters. See Sample.PARAMETER_DEFAULT_KEYS for some common names defined in the specification.

• model (Optional[SampleModel]) – A model using the simple model description (https://www.reflectometry.org/projects/simple_model)

name: str

category: Optional[str] = None

composition: Optional[str] = None

description: Optional[str] = None

size: Optional[ValueVector] = None

environment: Optional[List[str]] = None

sample_parameters: Optional[Dict[str, Union[Value, ValueRange, ValueVector, ComplexValue, AlternatingField]]] = None

model: Optional[SampleModel] = None

PARAMETER_DEFAULT_KEYS = ['temperature', 'magnetic_field', 'electric_potential', 'electric_current', 'electric_ac_field']

comment: Optional[str] = None

class orsopy.fileio.Software(name, version=None, platform=None, comment=None)

Bases: Header

Software description.

Parameters:

• name (str) – Software name.

• version (Optional[str]) – Version identified for the software.

• platform (Optional[str]) – Operating system.

name: str

version: Optional[str] = None

platform: Optional[str] = None

yaml_representer(dumper)

comment: Optional[str] = None

class orsopy.fileio.Value(magnitude, unit=None, error=None, offset=None, comment=None)

Bases: Header

A value or list of values with an optional unit.

magnitude: float

unit: Optional[str] = None

error: Optional[ErrorValue] = None

offset: Optional[float] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns the value as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.ValueRange(min, max, unit=None, individual_magnitudes=None, offset=None, comment=None)

Bases: Header

A range or list of ranges with mins, maxs, and an optional unit.

min: float

max: float

unit: Optional[str] = None

individual_magnitudes: Optional[List[float]] = None

offset: Optional[float] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns a (min, max) tuple of values as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.ValueVector(x, y, z, unit=None, error=None, comment=None)

Bases: Header

A vector or list of vectors with an optional unit. For vectors relating to the sample, such as polarisation, the follow definitions are used.

Parameters:

• x (float) – is defined as parallel to the radiation beam, positive going with the beam direction.

• y (float) – is defined from the other two based on the right hand rule.

• z (float) – is defined as normal to the sample surface, positive direction in scattering direction.

• unit (Optional[str]) – SI unit string.

x: float

y: float

z: float

unit: Optional[str] = None

error: Optional[ErrorValue] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns a (x, y, z) tuple of values as converted to the given unit.

comment: Optional[str] = None

orsopy.fileio.load_nexus(fname)

Return type:

List[OrsoDataset]

orsopy.fileio.load_orso(fname)

Parameters:

fname (Union[TextIO, str]) – The Orso file to load.

Return type:

List[OrsoDataset]

Returns:

OrsoDataset objects for each dataset contained within the ORT file.

orsopy.fileio.save_nexus(datasets, fname, comment=None)

Return type:

BinaryIO

orsopy.fileio.save_orso(datasets, fname, comment=None, data_separator='')

Saves an ORSO file. Each of the datasets must have a unique OrsoDataset.info.data_set attribute. If that attribute is not set, it is given an integer value corresponding to it’s position in the list.

Parameters:

• datasets (List[OrsoDataset]) – List of OrsoDataset to save into the Orso file.

• fname (Union[TextIO, str]) – The file name to save to.

• comment (Optional[str]) – Comment to write at the top of Orso file.

• data_separator (str) – Optional string of newline characters to separate multiple datasets.

Raises:

ValueError – If the OrsoDataset.info.data_set values are not unique.

Return type:

None

Submodules

orsopy.fileio.base module

Implementation of the base classes for the ORSO header.

exception orsopy.fileio.base.ORSOResolveError

Bases: ValueError

exception orsopy.fileio.base.ORSOSchemaWarning

Bases: RuntimeWarning

class orsopy.fileio.base.Header

Bases: object

The super class for all the items in the orso module.

classmethod from_dict(data_dict)

Create class from dictionary as is returned from yaml file reader.

If user-supplied attributes are provided, they are not passed to the constructor but applied after instance generation.

property user_data

classmethod empty()

Create an empty instance of this item containing all non-option attributes as None.

Return type:

Header

Returns:

Empty class.

static asdict(header)

Static method for to_dict().

Parameters:

header (Header) – Object to convert to dictionary.

Return type:

dict

Returns:

Dictionary result.

to_dict()

Produces a clean dictionary of the Header object, removing any optional attributes with the value None or default value.

Return type:

dict

Returns:

Cleaned dictionary.

to_yaml()

Return the yaml string for the Header item

Return type:

str

Returns:

Yaml string

yaml_representer(dumper)

yaml_representer_compact(dumper)

to_nexus(root=None, name=None)

Produces an HDF5 representation of the Header object, removing any optional attributes with the value None.

Returns:

HDF5 object

class orsopy.fileio.base.OrsoDumper(stream, default_style=None, default_flow_style=False, canonical=None, indent=None, width=None, allow_unicode=None, line_break=None, encoding=None, explicit_start=None, explicit_end=None, version=None, tags=None, sort_keys=True)

Bases: SafeDumper

represent_data(data)

orsopy.fileio.base.get_unit_registry()

class orsopy.fileio.base.ErrorValue(error_value, error_type=None, value_is=None, distribution=None, comment=None)

Bases: Header

Information about errors on a value.

error_value: float

error_type: Optional[Literal['uncertainty', 'resolution']] = None

value_is: Optional[Literal['sigma', 'FWHM']] = None

distribution: Optional[Literal['gaussian', 'triangular', 'uniform', 'lorentzian']] = None

yaml_representer(dumper)

property sigma

Return value converted to standard deviation.

The conversion factors can be found in common statistics and experimental physics text books or derived manually solving the variance definition integral. (e.g. Dekking, Michel (2005). A modern introduction to probability and statistics : understanding why and how. Springer, London, UK:) Values and some references available on Wikipedia, too.

comment: Optional[str] = None

class orsopy.fileio.base.Value(magnitude, unit=None, error=None, offset=None, comment=None)

Bases: Header

A value or list of values with an optional unit.

magnitude: float

unit: Optional[str] = None

error: Optional[ErrorValue] = None

offset: Optional[float] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns the value as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.base.ComplexValue(real, imag=None, unit=None, error=None, comment=None)

Bases: Header

A value or list of values with an optional unit.

real: float

imag: Optional[float] = None

unit: Optional[str] = None

error: Optional[ErrorValue] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns the complex value as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.base.ValueRange(min, max, unit=None, individual_magnitudes=None, offset=None, comment=None)

Bases: Header

A range or list of ranges with mins, maxs, and an optional unit.

min: float

max: float

unit: Optional[str] = None

individual_magnitudes: Optional[List[float]] = None

offset: Optional[float] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns a (min, max) tuple of values as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.base.ValueVector(x, y, z, unit=None, error=None, comment=None)

Bases: Header

A vector or list of vectors with an optional unit. For vectors relating to the sample, such as polarisation, the follow definitions are used.

Parameters:

• x (float) – is defined as parallel to the radiation beam, positive going with the beam direction.

• y (float) – is defined from the other two based on the right hand rule.

• z (float) – is defined as normal to the sample surface, positive direction in scattering direction.

• unit (Optional[str]) – SI unit string.

x: float

y: float

z: float

unit: Optional[str] = None

error: Optional[ErrorValue] = None

yaml_representer(dumper)

as_unit(output_unit)

Returns a (x, y, z) tuple of values as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.base.AlternatingField(amplitude, frequency, phase=None, comment=None)

Bases: Header

A physical field with regular variations as AC magnetic field.

amplitude: Value

frequency: Value

phase: Optional[Value] = None

comment: Optional[str] = None

class orsopy.fileio.base.Person(name, affiliation, contact=None, comment=None)

Bases: Header

Information about a person, including name, affiliation(s), and contact information.

name: str

affiliation: str

contact: Optional[str] = None

comment: Optional[str] = None

class orsopy.fileio.base.Column(name, unit=None, physical_quantity=None, flag_is=None, comment=None)

Bases: Header

Information about a data column.

name: str

unit: Optional[str] = None

physical_quantity: Optional[str] = None

flag_is: Optional[List[str]] = None

yaml_representer(dumper)

comment: Optional[str] = None

class orsopy.fileio.base.ErrorColumn(error_of, error_type=None, value_is=None, distribution=None, comment=None)

Bases: Header

Information about a data column.

error_of: str

error_type: Optional[Literal['uncertainty', 'resolution']] = None

value_is: Optional[Literal['sigma', 'FWHM']] = None

distribution: Optional[Literal['gaussian', 'triangular', 'uniform', 'lorentzian']] = None

yaml_representer(dumper)

property name

A convenience property to allow programs to get a valid name attribute for any column.

property to_sigma

The multiplicative factor needed to convert a FWHM to sigma.

The conversion factors can be found in common statistics and experimental physics text books or derived manually solving the variance definition integral. (e.g. Dekking, Michel (2005). A modern introduction to probability and statistics : understanding why and how. Springer, London, UK:) Values and some references available on Wikipedia, too.

comment: Optional[str] = None

class orsopy.fileio.base.ContentHash(digest, algorithm, comment=None)

Bases: Header

A hash of some content, using standard algorithms

digest: str

algorithm: Literal['sha1', 'sha256', 'sha384', 'sha512', 'sha3_256', 'sha3_512']

classmethod from_file(fname, algorithm='sha1')

check_file(fname)

Check that a file has the same content hash.

comment: Optional[str] = None

class orsopy.fileio.base.File(file, timestamp=None, hash=None, comment=None)

Bases: Header

A file with file path and a last modified timestamp.

file: str

timestamp: Optional[datetime] = None

hash: Optional[ContentHash] = None

comment: Optional[str] = None

exception orsopy.fileio.base.NotOrsoCompatibleFileError

Bases: ValueError

orsopy.fileio.base.json_datetime_trap(obj)

orsopy.fileio.base.enum_trap(obj)

orsopy.fileio.base.nexus_value_converter(obj)

orsopy.fileio.data_source module

Implementation of the data_source for the ORSO header.

class orsopy.fileio.data_source.Experiment(title, instrument, start_date, probe, facility=None, proposalID=None, doi=None, comment=None)

Bases: Header

A definition of the experiment performed.

Parameters:

• title (str) – Proposal or project title.

• instrument (str) – Reflectometer identifier.

• start_date (datetime) – Start date for the experiment.

• probe (Literal['neutron', 'x-ray']) – Radiation probe, either 'neutron' or 'x-ray'.

• facility (Optional[str]) – Facility where the experiment was performed.

• proposalID (Optional[str]) – Identifier for experiment at a facility.

• doi (Optional[str]) – Digital object identifier for the experiment, possibly provided by the facility.

title: str

instrument: str

start_date: datetime

probe: Literal['neutron', 'x-ray']

facility: Optional[str] = None

proposalID: Optional[str] = None

doi: Optional[str] = None

comment: Optional[str] = None

class orsopy.fileio.data_source.Sample(name, category=None, composition=None, description=None, size=None, environment=None, sample_parameters=None, model=None, comment=None)

Bases: Header

A description of the sample measured.

Parameters:

• name (str) – An identified for the individual sample or the subject and state being measured.

• category (Optional[str]) – Simple sample description, front (beam side) / back, each side should be one of 'solid/liquid', 'liquid/solid', 'gas/liquid', 'liquid/liquid', 'solid/gas', 'gas/solid'.

• composition (Optional[str]) – Notes on the nominal composition of the sample e.g. Si | SiO2 (20 angstrom) | Fe (200 angstrom) | air (beam side).

• description (Optional[str]) – Further details of the sample, e.g. size.

• size (Optional[ValueVector]) – Sample size in x, y, z direction, where z is parallel to the surface normal and x is along the beam direction (important for footprint correction).

• environment (Optional[List[str]]) – Name of the sample environment device(s).

• sample_parameters (Optional[Dict[str, Union[Value, ValueRange, ValueVector, ComplexValue, AlternatingField]]]) – Dictionary of sample parameters. See Sample.PARAMETER_DEFAULT_KEYS for some common names defined in the specification.

• model (Optional[SampleModel]) – A model using the simple model description (https://www.reflectometry.org/projects/simple_model)

name: str

category: Optional[str] = None

composition: Optional[str] = None

description: Optional[str] = None

size: Optional[ValueVector] = None

environment: Optional[List[str]] = None

sample_parameters: Optional[Dict[str, Union[Value, ValueRange, ValueVector, ComplexValue, AlternatingField]]] = None

model: Optional[SampleModel] = None

PARAMETER_DEFAULT_KEYS = ['temperature', 'magnetic_field', 'electric_potential', 'electric_current', 'electric_ac_field']

comment: Optional[str] = None

class orsopy.fileio.data_source.Polarization(value)

Bases: str, Enum

Polarization of the beam used for the reflectivity.

Neutrons: The first symbol indicates the magnetisation direction of the incident beam, the second symbol indicates the direction of the scattered beam. If either polarization or analysis are not employed the symbol is replaced by “o”.

X-rays: Uses the conventional names pi, sigma, left and right. In experiments with polarization analysis the incident and outgoing polarizations are separated with an underscore “_”.

unpolarized = 'unpolarized'

po = 'po'

mo = 'mo'

op = 'op'

om = 'om'

mm = 'mm'

mp = 'mp'

pm = 'pm'

pp = 'pp'

pi = 'pi'

sigma = 'sigma'

left = 'left'

right = 'right'

pi_pi = 'pi_pi'

sigma_sigma = 'sigma_sigma'

pi_sigma = 'pi_sigma'

sigma_pi = 'sigma_pi'

yaml_representer(dumper)

class orsopy.fileio.data_source.InstrumentSettings(incident_angle, wavelength, polarization=Polarization.unpolarized, configuration=None, comment=None)

Bases: Header

Settings associated with the instrumentation.

Parameters:

• incident_angle (Union[Value, ValueRange]) – Angle (range) of incidence.

• wavelength (Union[Value, ValueRange]) – Neutron/x-ray wavelength (range).

• polarization (Union[Polarization, ValueVector]) – Radiation polarization as one of 'unpolarized', 'p', 'm', 'pp', 'pm', 'mp', 'mm', or a orsopy.fileio.base.ValueVector.

• configuration (Optional[str]) – Description of the instreument configuration (full polarized/liquid surface/etc).

incident_angle: Union[Value, ValueRange]

wavelength: Union[Value, ValueRange]

polarization: Union[Polarization, ValueVector] = 'unpolarized'

configuration: Optional[str] = None

comment: Optional[str] = None

class orsopy.fileio.data_source.Measurement(instrument_settings, data_files, additional_files=None, scheme=None, comment=None)

Bases: Header

The measurement elements for the header.

Parameters:

• instrument_settings (InstrumentSettings) – Instrumentation details.

• data_files (List[Union[File, str]]) – Raw data files produced in the measurement.

• additional_files (Optional[List[Union[File, str]]]) – Raw reference files used in the reduction.

• scheme (Optional[Literal['angle- and energy-dispersive', 'angle-dispersive', 'energy-dispersive']]) – Measurement scheme (one of 'angle-dispersive', 'energy-dispersive'/'angle- and energy-dispersive').

instrument_settings: InstrumentSettings

data_files: List[Union[File, str]]

additional_files: Optional[List[Union[File, str]]] = None

scheme: Optional[Literal['angle- and energy-dispersive', 'angle-dispersive', 'energy-dispersive']] = None

comment: Optional[str] = None

class orsopy.fileio.data_source.DataSource(owner, experiment, sample, measurement, comment=None)

Bases: Header

The data_source object definition.

Parameters:

• owner (Person) – This refers to the actual owner of the data set, i.e. the main proposer or the person doing the measurement on a lab reflectometer.

• experiment (Experiment) – Details of the experimental.

• sample (Sample) – Sample information.

• measurement (Measurement) – Measurement specifics.

owner: Person

experiment: Experiment

sample: Sample

measurement: Measurement

comment: Optional[str] = None

orsopy.fileio.model_language module

Implementation of the simplified model language for the ORSO header.

It includes parsing of models from header or different input information and resolving the model to a simple list of slabs.

orsopy.fileio.model_language.find_idx(string, start, value)

orsopy.fileio.model_language.find_closing(string, start)

class orsopy.fileio.model_language.SubStack(repetitions=1, stack=None, sequence=None, sub_stack_class='SubStack', environment=None, comment=None)

Bases: Header, SubStackType

repetitions: int = 1

stack: Optional[str] = None

sequence: Optional[List[Layer]] = None

sub_stack_class: Optional[Literal['SubStack']] = 'SubStack'

environment: Union[Material, Composit, str, None] = None

original_name = None

resolve_names(resolvable_items)

resolve_defaults(defaults)

resolve_to_blocks()

Return type:

List[Union[Layer, SubStackType]]

resolve_to_layers()

Return type:

List[Layer]

comment: Optional[str] = None

class orsopy.fileio.model_language.ItemChanger(like, but, comment=None)

Bases: Header

Allows to define a simple change in SubStackType item by just updating a selected set of parameters.

like: str

but: dict

original_name = None

comment: Optional[str] = None

class orsopy.fileio.model_language.SampleModel(stack, origin=None, sub_stacks=None, layers=None, materials=None, composits=None, globals=None, reference=None, comment=None)

Bases: Header

stack: str

origin: Optional[str] = None

sub_stacks: Optional[Dict[str, Union[ItemChanger, SubStack, FunctionTwoElements]]] = None

layers: Optional[Dict[str, Layer]] = None

materials: Optional[Dict[str, Material]] = None

composits: Optional[Dict[str, Composit]] = None

globals: Optional[ModelParameters] = None

reference: Optional[str] = None

property resolvable_items

resolve_stack()

resolve_to_blocks()

Return type:

List[Union[Layer, SubStackType]]

comment: Optional[str] = None

resolve_to_layers()

Return type:

List[Layer]

orsopy.fileio.model_language.T

alias of SubStack

orsopy.fileio.orso module

Implementation of the top level class for the ORSO header.

class orsopy.fileio.orso.Orso(data_source, reduction, columns, data_set=None, **user_data)

Bases: Header

The Orso object collects the necessary metadata.

Parameters:

• data_source (DataSource) – Information about the origin and ownership of the raw data.

• reduction (Reduction) – Details of the data reduction that has been performed. The content of this section should contain enough information to rerun the reduction.

• columns (List[Union[Column, ErrorColumn]]) – Information about the columns of data that will be contained in the file.

• data_set (Union[int, str, None]) – An identifier for the data set, i.e. if there is more than one data set in the object.

data_source: DataSource

reduction: Reduction

columns: List[Union[Column, ErrorColumn]]

data_set: Union[int, str, None] = None

classmethod empty()

Create an empty instance of the ORSO header with all non-optional attributes as None.

Return type:

Orso

Returns:

Empty Orso class, within minimum required columns

column_header()

An information string that explains what each of the columns in a dataset corresponds to.

Return type:

str

Returns:

Explanatory string.

from_difference(other_dict)

Constructs another Orso instance from self, and a dict containing updated header information.

Parameters:

other_dict (dict) – Contains updated header information.

Return type:

Orso

Returns:

A new Orso object constructed from self, and the updated header information.

to_difference(other)

A dictionary containing the difference in header information between two Orso objects.

Parameters:

other (Orso) – Other header to diff with.

Return type:

dict

Returns:

Dictionary of the header information difference.

to_dict()

Adds the user data to the returned dictionary.

comment: Optional[str] = None

class orsopy.fileio.orso.OrsoDataset(info, data)

Bases: object

Parameters:

• info (Orso) – The header information for the reflectivity measurement

• data (Union[ndarray, Sequence[ndarray], Sequence[Sequence]]) – The numerical data associated with the reflectivity measurement. The data has shape (npnts, ncols).

Raises:

ValueError – When ncols != len(self.info.columns).

info: Orso

data: Union[ndarray, Sequence[ndarray], Sequence[Sequence]]

classmethod from_dict(data_dict)

header()

The header string for the ORSO file.

Return type:

str

Returns:

Header string.

diff_header(other)

Return a header string that only contains changes to other OrsoDataset ensure that data_set is the first entry.

Parameters:

other (OrsoDataset) – Other OrsoDataset to compare against.

Return type:

str

Returns:

Header string with only changes.

save(fname)

Save the OrsoDataset.

Parameters:

fname (Union[TextIO, str]) – The file name to save to.

orsopy.fileio.orso.save_orso(datasets, fname, comment=None, data_separator='')

Saves an ORSO file. Each of the datasets must have a unique OrsoDataset.info.data_set attribute. If that attribute is not set, it is given an integer value corresponding to it’s position in the list.

Parameters:

• datasets (List[OrsoDataset]) – List of OrsoDataset to save into the Orso file.

• fname (Union[TextIO, str]) – The file name to save to.

• comment (Optional[str]) – Comment to write at the top of Orso file.

• data_separator (str) – Optional string of newline characters to separate multiple datasets.

Raises:

ValueError – If the OrsoDataset.info.data_set values are not unique.

Return type:

None

orsopy.fileio.orso.load_orso(fname)

Parameters:

fname (Union[TextIO, str]) – The Orso file to load.

Return type:

List[OrsoDataset]

Returns:

OrsoDataset objects for each dataset contained within the ORT file.

orsopy.fileio.orso.load_nexus(fname)

Return type:

List[OrsoDataset]

orsopy.fileio.orso.save_nexus(datasets, fname, comment=None)

Return type:

BinaryIO

orsopy.fileio.reduction module

The reduction elements for the ORSO header

class orsopy.fileio.reduction.Software(name, version=None, platform=None, comment=None)

Bases: Header

Software description.

Parameters:

• name (str) – Software name.

• version (Optional[str]) – Version identified for the software.

• platform (Optional[str]) – Operating system.

name: str

version: Optional[str] = None

platform: Optional[str] = None

yaml_representer(dumper)

comment: Optional[str] = None

class orsopy.fileio.reduction.Reduction(software, timestamp=None, creator=None, corrections=None, computer=None, call=None, script=None, binary=None, comment=None)

Bases: Header

A description of the reduction that has been performed.

Parameters:

• software (Software) – Software used for reduction.

• timestamp (Optional[datetime]) – Datetime of reduced file creation.

• creator (Optional[Person]) – The person or routine who created the reduced file.

• corrections (Optional[List[str]]) – A list of the corrections that have been performed.

• computer (Optional[str]) – Name of the reduction machine.

• call (Optional[str]) – Command line call or similar.

• script (Optional[str]) – Path to reduction script or notebook.

• binary (Optional[str]) – Path to full reduction information file.

software: Software

timestamp: Optional[datetime] = None

creator: Optional[Person] = None

corrections: Optional[List[str]] = None

computer: Optional[str] = None

call: Optional[str] = None

script: Optional[str] = None

binary: Optional[str] = None

comment: Optional[str] = None

orsopy.fileio.typing_backport module

Module for compatibility with Python <3.8. Requires the typing_extensions module to be installed.

orsopy.fileio.typing_backport.get_args(annotation)

orsopy.fileio.typing_backport.get_origin(annotation)