scippneutron.io.cif.CIF#

class scippneutron.io.cif.CIF(name='', *, comment='')[source]#

A builder for CIF files.

This class implements a builder pattern for defining the contents of a CIF file. See the module documentation of cif for examples.

__init__(name='', *, comment='')[source]#

Methods

`__init__`([name, comment])
`copy`()	Return a copy of this builder.
`save`(fname)
`with_authors`(*authors)	Add one or more authors.
`with_beamline`(beamline[, source, comment])	Add beamline information.
`with_measurement`(measurement, *[, comment])	Add measurement metadata.
`with_powder_calibration`(cal, *[, comment])	Add a powder calibration table.
`with_reduced_powder_data`(data, *[, comment])	Add a loop with reduced powder data.
`with_reducers`(*reducers)	Add one or more programs that were used to reduce the software.

Attributes

`comment`	Optional comment that can be written at the top of the file.
`name`
`schema`	CIF schemas used for the file.

property comment: str#: Optional comment that can be written at the top of the file.

copy()[source]#

Return a copy of this builder.

Return type:: CIF

save(fname)[source]#

Parameters:: fname (str | Path | TextIO) – Path or file handle for the output file.
Return type:: None

property schema: set[CIFSchema]#: CIF schemas used for the file.

with_authors(*authors)[source]#

Add one or more authors.

Parameters:: authors (Person) – Authors to add to this CIF object.
Returns:: CIF – A builder with added calibration data.

with_beamline(beamline, source=None, *, comment='')[source]#

Add beamline information.

Return type:: CIF

with_measurement(measurement, *, comment='')[source]#

Add measurement metadata.

Attention

Standard CIF does not define a way to encode all data in a Measurement object. This function uses custom keys wherever there is no standard CIF key. These custom keys are prefixed with sc_meas. (The standard defines pd_meas.)

Parameters:

measurement (Measurement) – Encodes information about the measurement (and experiment) of the data.
comment (str, default: '') – Optional comment to add above the measurement chunk.

Returns:

CIF – A builder with added measurement metadata.

with_powder_calibration(cal, *, comment='')[source]#

Add a powder calibration table.

The calibration data encode the following transformation from d-spacing to time-of-flight:

\[t = \sum_{i=0}^N\, c_i d^{p_i}\]

where \(c_i\) is the i-th element of cal and \(p^{p_i}\) is the i-th element of cal.coords['power'].

Parameters:

cal (DataArray) – The data are the calibration coefficients (possibly with variances). Must have a coordinate called 'power' defining \(p\) in the equation above.
comment (str, default: '') – Optional comment that can be written above the data in the file.

Returns:

CIF – A builder with added calibration data.

Examples

Add a mockup calibration table:

>>> import scipp as sc
>>> from scippneutron.io import cif
>>> cal = sc.DataArray(
...     sc.array(dims=['cal'], values=[3.4, 0.2]),
...     coords={'power': sc.array(dims=['cal'], values=[0, 1])},
... )
>>> cif_ = cif.CIF('powder-calibration')
>>> cif_ = cif_.with_powder_calibration(cal)

with_reduced_powder_data(data, *, comment='')[source]#

Add a loop with reduced powder data.

The input must be 1-dimensional with a dimension name in ('tof', 'dspacing'). The data array may also have a name in ('intensity_net', 'intensity_norm', 'intensity_total'). If the name is not set, it defaults to 'intensity_norm', which is appropriate for typical outputs from data reduction. See COMCIFS/Powder_Dictionary

The data gets written as intensity along a single coord whose name matches the dimension name. Standard uncertainties are also written if present.

The unit of the coordinate must match the requirement of pdCIF.

Parameters:

data (DataArray) – 1-dimensional data array with a recognized dimension name
comment (str, default: '') – Optional comment that can be written above the data in the file.

Returns:

CIF – A builder with added reduced data.

Examples

Make mockup powder diffraction data:

>>> import scipp as sc
>>> tof = sc.array(dims=['tof'], values=[1.2, 1.4, 2.3], unit='us')
>>> intensity = sc.array(
...     dims=['tof'],
...     values=[13.6, 26.0, 9.7],
...     variances=[0.7, 1.1, 0.5],
... )

Add to a CIF builder:

>>> from scippneutron.io import cif
>>> cif_ = cif.CIF('reduced-data')
>>> da = sc.DataArray(intensity, coords={'tof': tof})
>>> cif_ = cif_.with_reduced_powder_data(da)

with_reducers(*reducers)[source]#

Add one or more programs that were used to reduce the software.

Parameters:: reducers (str) – Pieces of software that were used to reduce the data. Each string is one piece of software in freeform notation. It is recommended to include the program name and version.
Returns:: CIF – A builder with added calibration data.