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).

from orsopy import fileio
from orsopy.fileio import (Reduction, Person, Orso, Experiment,
                           Sample, DataSource, Measurement, InstrumentSettings)
import numpy as np
import datetime

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. In this example we fill out the experiment details and then wrap them in the appropriate class.

title = 'my title'
instrument = 'PLATYPUS'
start_date = datetime.date.today()  # This needs to be an object of the type datetime
probe = 'neutron'
facility = 'ESS'
proposalID = 999999
doi = f'10.5286/ISIS.E.RB{99999}'

experiment = Experiment(title, instrument, start_date, probe, facility, proposalID, doi)

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. What we show here is not the minimum needed to write an .ort file, rather the minium to fill out all the major fields with information which is likely to be available at time of writing.

We now write out the user and sample details, but note that the sample can be alot more descriptive than just a name.

user_name = 'Jos Cooper'
user_affil = 'ESS'

user = Person(user_name, user_affil)

# Now fill the sample details
sample_name = 'Silicon'

sample = Sample(sample_name)

# The measurement details needs some instrument settings assigned first
angle = 0.3  # This can be a float, or a range, though currently not a list
wavelength = (1.8, 8.8)  # Again a float or range

instrument_settings = InstrumentSettings(angle, wavelength)

# Now add the instrument settings to the names of the files used
files = ['test_data.raw']  # A list of all raw files used reduced

measurment = Measurement(instrument_settings, files)

We can now wrap together the user, experiment, sample and measurement information into a single object.

data_source_info = DataSource(user, experiment, sample, measurment)

It is not possible to write an .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.

# Interpreted units are ["1/angstrom", "1/nm", "1", "1/s", None]
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]
# We can also make some data so that this code example will write something out
q = np.array([0.01,0.02,0.03])
R = np.array([0.1,0.2,0.3])
dR = np.array([0.001,0.002,0.003])
dq = q * 0.02

Any required metadata that is not included in the head will be written in the file as containing null.

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.

orso_class = Orso(data_source_info, reduction=Reduction('My own code'), columns=header.columns)  # reduction can also be assigned out of this funciton call
dataset = fileio.orso.OrsoDataset(info=orso_class, 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 the first input is a list of datasets

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.