Usage

The easiest way to use orsopy.fileio (the module of orsopy that includes file reading and writing) to produce metadata-rich .ort reduced reflectometry files involves integrating this into your data reduction workflow. Early in the workflow, the orsopy.fileio should be imported and an empty orsopy.fileio.orso.Orso header object (here we also import numpy which will be used later).

import numpy as np
from orsopy import fileio

header = fileio.orso.Orso.empty()

Having created the empty header object we can start to populate the appropriate components of it. It is generally a good idea to populate the components as particular steps occur in the reduction process. For example, if we want to identify the probing radiation as neutrons, we include this as follows.

header.data_source.experiment.probe = 'neutrons'

Full details of the different components that can be populated can be found in the documentation here or in the file format specification. Note that this specification includes information regarding the required and optional components to be included for a file to be considered a valid .ort file. It is not possible to write a .ort file without defining the columns present in the dataset, in this example we will have four columns of data, namely q, R, dR and dq (the final column is a description of the resolution function). Columns are defined as follows, using the orsopy.fileio.base.Column and orsopy.fileio.base.ErrorColumn class objects (note that there are other base classes that can be used for a variety of objects).

q_column = fileio.base.Column(name='Qz', unit='1/angstrom', physical_quantity='wavevector transfer')
r_column = fileio.base.Column(name='R', unit=None, physical_quantity='reflectivity')
dr_column = fileio.base.ErrorColumn(error_of='R', error_type='uncertainty', value_is='sigma')
dq_column = fileio.base.ErrorColumn(error_of='Qz', error_type='resolution', value_is='sigma')

header.columns = [q_column, r_column, dr_column, dq_column]

Any required metadata that is not included in the head will be written in the file as containing null. Having populated the metadata, we can now ensure that the metadata is correct with the following,

correct_header = fileio.orso.Orso(**header.to_dict())

This will produce a new object, if the metadata is correct.

Now, we then want to assign the data that we want to write (this will be after your data reduction has been performed). This is achieved by producing a fileio.orso.OrsoDataset object, which takes the header and the relevant data columns (below these are q, R, dR, and dq) as inputs.

dataset = fileio.orso.OrsoDataset(info=header, data=np.array([q, R, dR, dq]).T)

The dataset can then be saved with the following function, where 'my_file.ort' is the name for the file to be saved under.

fileio.orso.save_orso(datasets=[dataset], fname='my_file.ort')

Note that if you want to save more than one dataset in a single file, this can be achieved by including these in the list that is passed to this function.