orsopy.fileio package

Submodules

Module contents

Implementation of the Orso class that defined the header.

class orsopy.fileio.Column(name, unit=None, physical_quantity=None, flag_is=None, comment=None)[source]

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)[source]

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)[source]: Returns the complex value as converted to the given unit.

comment: Optional[str] = None

class orsopy.fileio.DataSource(owner, experiment, sample, measurement, comment=None)[source]

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)[source]

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)[source]

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, comment=None)[source]

Bases: Header

A file with file path and a last modified timestamp.

file: str

timestamp: Optional[datetime] = None

comment: Optional[str] = None

class orsopy.fileio.Header[source]

Bases: object

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

classmethod from_dict(data_dict)[source]

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()[source]

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

Return type:: Header
Returns:: Empty class.

static asdict(header)[source]

Static method for to_dict().

Parameters:: header (Header) – Object to convert to dictionary.
Return type:: dict
Returns:: Dictionary result.

to_dict()[source]

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

Return type:: dict
Returns:: Cleaned dictionary.

to_yaml()[source]

Return the yaml string for the Header item

Return type:: str
Returns:: Yaml string

yaml_representer(dumper)[source]

yaml_representer_compact(dumper)[source]

to_nexus(root=None, name=None)[source]

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)[source]

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)[source]

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)[source]

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()[source]

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()[source]

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)[source]

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)[source]

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()[source]: Adds the user data to the returned dictionary.

comment: Optional[str] = None

class orsopy.fileio.OrsoDataset(info, data)[source]

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)[source]

header()[source]

The header string for the ORSO file.

Return type:: str
Returns:: Header string.

diff_header(other)[source]

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)[source]

Save the OrsoDataset.

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

class orsopy.fileio.Person(name, affiliation, contact=None, comment=None)[source]

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)[source]

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)[source]

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

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)[source]

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)[source]

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)[source]

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)[source]: 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)[source]

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)[source]: 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)[source]

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)[source]: Returns a (x, y, z) tuple of values as converted to the given unit.

comment: Optional[str] = None

orsopy.fileio.load_nexus(fname)[source]

Return type:: List[OrsoDataset]

orsopy.fileio.load_orso(fname)[source]

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)[source]

Return type:: BinaryIO

orsopy.fileio.save_orso(datasets, fname, comment=None, data_separator='')[source]

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 package

Subpackages

Submodules

Module contents