refnx.reduce
- class refnx.reduce.AutoReducer(direct_beams, scale=1, reduction_options=None, data_folder='.')[source]
Bases:
object
Auto-reduces reflectometry data.
Watches a datafolder for new/modified NeXUS files and reduces them.
- Parameters
direct_beams (list of {str, h5data}) – list of str, or list of h5py file handles pointing to direct beam runs
scale (float or array-like) – Scale factors corresponding to each direct beam.
reduction_options (dict, or list of dict) – Specifies the reduction options for each of the direct beams. A default set of options is provided by refnx.reduce.ReductionOptions.
data_folder ({str, Path}) – Path to the data folder containing the data to be reduced.
Notes
Requires that the ‘watchdog’ package be installed. Starts two threads that are responsible for doing the reduction.
- match_datasets(dct)[source]
Finds all the datasets in AutoReducer.redn_cache that share an identical dct[“sample_name”], but may have been measured at different angles.
- Parameters
dct (dict) – dct.keys() = [“fname”, “sample_name”, “omega”]
- Returns
datasets – Datasets that share the same sample_name as dct[‘sample_name’]
- Return type
list of refnx.dataset.Data1D
- match_direct_beam(rb)[source]
Finds the direct beam associated with a reflection measurement. Matching is done by finding identical collimation conditions.
- Parameters
rb ({PlatypusNexus, SpatzNexus}) – The reflectometry run.
- Returns
db – The direct beam file name that matches the reflection measurement This is used to look up an entry in AutoReducer.direct_beams.
- Return type
- splice_datasets(ds)[source]
Combines datasets together.
- Parameters
ds (list of refnx.dataset.Data1D) – The datasets to splice together.
- Returns
fname – The name of the combined dataset
- Return type
Notes
The combined dataset is saved as f”c_{d.filename}.dat”, where d is the dataset with the lowest average Q value from ds.
- class refnx.reduce.BatchReducer(filename, data_folder=None, verbose=True, persistent=True, trim_trailing=True, reduction_options=None, prefix='PLP')[source]
Bases:
object
Batch reduction of reflectometry data based on spreadsheet metadata.
Example
>>> from refnx.reduce import BatchReducer >>> data_folder = r'V:\data\current' >>> b = BatchReducer('reduction.xls', data_folder=data_folder) >>> b.reduce()
The spreadsheet must have columns:
reduce name scale refl1 refl2 refl3 dir1 dir2 dir3
Only rows where the value of the reduce column is 1 and where the sample name is set will be processed.
- class refnx.reduce.Catalogue(h5d)[source]
Bases:
object
Extract relevant parts of a NeXus file for reflectometry reduction
- property datafile_number
- class refnx.reduce.PlatypusNexus(h5data)[source]
Bases:
ReflectNexus
Processes Platypus NeXus files to produce an intensity vs wavelength spectrum
- Parameters
h5data ({HDF5 NeXus file, str, Path}) – An HDF5 NeXus file for Platypus, or a str/Path specifying the path to one
- chod(omega=0.0, twotheta=0.0, scanpoint=0)[source]
Calculates the flight length of the neutrons in the Platypus instrument.
- create_detector_norm(h5norm)[source]
Produces a detector normalisation array for a neutron detector. Here we average over N, T and X to provide a relative efficiency for each y wire.
- Parameters
h5norm (hdf5 file) – Containing a flood field run (water)
- Returns
norm, norm_sd – 1D array containing the normalisation data for each y pixel
- Return type
array_like
- class refnx.reduce.PlatypusReduce(direct, data_folder=None, **kwds)[source]
Bases:
ReflectReduce
Reduces Platypus reflectometer data to give the specular reflectivity. Offspecular data maps are also produced.
- Parameters
direct (string, hdf5 file-handle or PlatypusNexus object) – A string containing the path to the direct beam hdf5 file, the hdf5 file itself, or a PlatypusNexus object.
data_folder (str, optional) – Folder where the datafiles are stored.
Examples
>>> from refnx.reduce import PlatypusReduce >>> reducer = PlatypusReduce('PLP0000711.nx.hdf') >>> datasets, reduced = reducer.reduce('PLP0000711.nx.hdf', ... rebin_percent=2)
- class refnx.reduce.PolarisationEfficiency(wavelength_axis, config='full')[source]
Bases:
object
Describes the polarisation efficiency of a neutron scattering system with the option of having a polariser, flipper-1, flipper-2, and analyser in the system.
The dimensions of processed spectra are (n_spectra, TOF). Since we expect that our efficiencies are purely wavelength dependent and not dependent upon the spectra within a Nexus file, we neglect the n_spectra axis when dealing with polarisation efficiencies.
- Parameters
wavelength_axis (numpy.array (T,)) – Array of wavelength bin centres to initialise the length of the (T, 4, 4) efficiency matrices.
config ({"full", "PF"}) – Indication of polariser/analyser configuration. If “full” is used, all polarising and flipping elements are taken into account. If “PF” is used, only the polariser and flipper are taken into account.
- custom_efficiencies(config)[source]
Define custom efficiency function for polariser, analyser, and flippers to reduce data. Recommended only for advanced users.
- standard_efficiencies(config)[source]
Define PLATYPUS polarisation efficiency matrices as described in the invited article in Rev. Sci. Instr. 83, 081301 (2012) `Polarization “Down Under”: The polarized time-of-flight neutron reflectometer PLATYPUS’ (https://doi.org/10.1063/1.4738579).
In this formulation, the relationship between raw spectra from each spin channel and the efficiency-corrected polarised reflectivity is shown by the matrix equation
I = F1 * F2 * P * A * R
where I and R are the (TOF, 4, 1) raw spectra and corrected reflectivity, & F1, F2, P, and A are the (TOF, 4, 4) efficiency matrices from the RF flippers, polariser and analyser.
This includes coefficients for the function f(x) = a - b * c ** x
- Parameters
config ({"full", "PF"}) –
- class refnx.reduce.PolarisedReduce(spin_set_direct)[source]
Bases:
object
Reduces a direct beam and reflected beam spinset to produce a polarised neutron reflectivity curve that is corrected for polarisation efficiency.
- Parameters
spin_set_direct (refnx.reduce.SpinSet) – Direct beam runs from a PNR experiment.
- spin_set_direct
Direct beams from PNR experiment
- Type
- reducers
- Dictionary of each measured spin channel
“dd” : refnx.reduce.PlatypusNexus (R–) “du” : refnx.reduce.PlatypusNexus or None (R-+) “ud” : refnx.reduce.PlatypusNexus or None (R+-) “uu” : refnx.reduce.PlatypusNexus (R++)
- Type
Examples
>>> from refnx.reduce import SpinSet, PolarisedReduce >>> direct_beams = SpinSet( ... down_down = 'PLP0012793.nx.hdf', ... up_up = 'PLP0012795.nx.hdf', ... up_down = 'PLP0012794.nx.hdf', ... down_up = 'PLP0012796.nx.hdf' ... ) >>> refl_beams = SpinSet( ... down_down = 'PLP0012785.nx.hdf', ... up_up = 'PLP0012787.nx.hdf', ... up_down = 'PLP0012786.nx.hdf', ... down_up = 'PLP0012788.nx.hdf' ... ) >>> reducer = PolarisedReduce(direct_beams) >>> datasets, reduced = reducer.reduce(refl_beams)
- reduce(spin_set_reflect, pol_eff=None, save=True, scale=1.0, **reduction_options)[source]
Reduce a refnx.reduce.SpinSet of polarised neutron reflected beams, and correct for the efficiency of the polariser system.
- Parameters
spin_set_reflect (refnx.reduce.SpinSet) – Spinset of reflected beams
pol_eff (refnx.reduce.PolarisationEfficiency, optional) – Input a defined polarisation efficiency of the polariser - flipper 1 - flipper 2 - analyser system.
reduction_options (dict, optional) – Reduction options to apply to every spin channel being reduced. This will override any individually defined reduction options for each spin channel
- spin_set_reflect
Reflected beams from PNR experiment
- Type
- class refnx.reduce.ReductionOptions(h5norm=None, lo_wavelength=2.5, hi_wavelength=19.0, background=True, direct=False, omega=None, twotheta=None, rebin_percent=1.0, wavelength_bins=None, normalise=True, integrate=-1, eventmode=None, event_folder=None, peak_pos=None, peak_pos_tol=None, background_mask=None, normalise_bins=True, manual_beam_find=None, event_filter=None, detailed_kernel=False, lopx_hipx=None)[source]
Bases:
dict
dict specifying the options for processing a Reflectometry dataset.
- Parameters
h5norm (str or HDF5 NeXus file) – If a str then h5norm is a path to the floodfield data, otherwise it is a hdf5 file handle containing the floodfield data.
lo_wavelength (float) – The low wavelength cutoff for the rebinned data (A).
hi_wavelength (float) – The high wavelength cutoff for the rebinned data (A).
background (bool) – Should a background subtraction be carried out?
direct (bool) – Is it a direct beam you measured? This is so a gravity correction can be applied (if the instrument needs one).
omega (float) – Expected angle of incidence of beam. If this is None, then the rough angle of incidence is obtained from the NeXus file.
twotheta (float) – Expected two theta value of specular beam. If this is None then the rough angle of incidence is obtained from the NeXus file.
rebin_percent (float) – Specifies the rebinning percentage for the spectrum. If rebin_percent is None, then no rebinning is done.
wavelength_bins (array_like) – The wavelength bins for rebinning. If wavelength_bins is not None then the rebin_percent parameter is ignored.
normalise (bool) – Normalise by the monitor counts.
integrate (int) –
Specifies which scanpoints to use.
integrate == -1 the spectrum is integrated over all the scanpoints.
integrate >= 0 the individual spectra are calculated individually. If eventmode is not None, or event_filter is not None then integrate specifies which scanpoint to examine.
eventmode (None or array_like) – If eventmode is None then the integrated detector image is used. If eventmode is an array then the array specifies the integration times (in seconds) for the detector image, e.g. [0, 20, 30] would result in two spectra. The first would contain data for 0 s to 20s, the second would contain data for 20 s to 30 s. This option can only be used when integrate >= -1. If eventmode has zero length (e.g. []), then a single time interval for the entire acquisition is used, [0, acquisition_time]. This would source the image from the eventmode file, rather than the NeXUS file. The two approaches will probably not give identical results, because the eventmode method adjusts the total acquisition time and beam monitor counts to the frame number of the last event detected (which may be quite different if the count rate is very low). This parameter is disregarded if event_filter is provided.
event_folder ({None, str, Path}) – Specifies the path for the eventmode data. If event_folder is None then the eventmode data is assumed to reside in the same directory as the NeXUS file. If event_folder is a string or Path, then the string specifies the path to the eventmode data.
peak_pos (-1, None, or (float, float)) –
Options for finding specular peak position and peak standard deviation.
- -1
use manual_beam_find.
- None
use the automatic beam finder, falling back to manual_beam_find if it’s provided.
- (float, float)
specify the peak and peak standard deviation. The peak standard deviation is used to calculate the width of the foreground region, unless lopx_hipx is specified.
peak_pos_tol (None or (float, float)) – Convergence tolerance for the beam position and width to be accepted from successive beam-finder calculations; see the tol parameter in the find_specular_ridge function.
background_mask (array_like) – An array of bool that specifies which y-pixels to use for background subtraction. Should be the same length as the number of y pixels in the detector image. Otherwise an automatic mask is applied (if background is True).
normalise_bins (bool) – Divides the intensity in each wavelength bin by the width of the bin. This allows one to compare spectra even if they were processed with different rebin percentages.
manual_beam_find (callable, optional) – A function which allows the location of the specular ridge to be determined. Has the signature f(detector, detector_err, name) where detector and detector_err is the detector image and its uncertainty, and name is a str specifying the name of the dataset. detector and detector_err have shape (n, t, {x, y}) where n is the number of detector images, t is the number of time-of-flight bins and x or y is the number of x or y pixels. The function should return a tuple, (centre, centre_sd, lopx, hipx, background_pixels). centre, centre_sd, lopx, hipx should be arrays of shape (n, ), specifying the beam centre, beam width (standard deviation), lowest pixel of foreground region, highest pixel of foreground region. background_pixels is a list of length n. Each of the entries should contain arrays of pixel numbers that specify the background region for each of the detector images.
event_filter (callable, optional) –
A function, that processes the event stream, returning a detector array, and a frame_count array. detector has shape (N, T, Y, X), where N is the number of detector images, T is the number of time bins (len(t_bins)), etc. frame_count has shape (N,) and contains the number of frames for each of the detector images. The frame_count is used to determine what fraction of the overall monitor counts should be ascribed to each detector image (by dividing by the total number of frames). The function has signature:
- detector, frame_count = event_filter(loaded_events,
t_bins=None, y_bins=None, x_bins=None)
loaded_events is a 4-tuple of numpy arrays: (f_events, t_events, y_events, x_events), where f_events contains the frame number for each neutron, landing at position x_events, y_events on the detector, with time-of-flight t_events.
detailed_kernel (bool) – whether a detailed resolution kernel is calculating during reduction.
lopx_hipx (tuple) – A two-tuple specifying the foreground region. For example, use of (120, 123) would use pixels 120, 121, 122, 123.
- class refnx.reduce.SpatzNexus(h5data)[source]
Bases:
ReflectNexus
Processes Spatz NeXus files to produce an intensity vs wavelength spectrum
- Parameters
h5data ({HDF5 NeXus file, str, Path}) – An HDF5 NeXus file for Spatz, or a str containing the path to one
- chod(omega=0.0, twotheta=0.0, scanpoint=0)[source]
Calculates the flight length of the neutrons in the Spatz instrument.
- create_detector_norm(h5norm)[source]
Produces a detector normalisation array for a neutron detector. Here we average over N, T and Y to provide a relative efficiency for each X wire.
- Parameters
h5norm (hdf5 file) – Containing a flood field run (water)
- Returns
norm, norm_sd – 1D array containing the normalisation data for each x pixel
- Return type
array_like
- class refnx.reduce.SpatzReduce(direct, data_folder=None, **kwds)[source]
Bases:
ReflectReduce
Reduces Spatz reflectometer data to give the specular reflectivity. Offspecular data maps are also produced.
- Parameters
direct (string, hdf5 file-handle or SpatzNexus object) – A string containing the path to the direct beam hdf5 file, the hdf5 file itself, or a SpatzNexus object.
data_folder (str, optional) – Where is the raw data stored?
Examples
>>> from refnx.reduce import SpatzReduce >>> reducer = SpatzReduce('SPZ0000711.nx.hdf') >>> datasets, reduced = reducer.reduce('SPZ0000711.nx.hdf', ... rebin_percent=2)
- class refnx.reduce.SpinChannel(value)[source]
Bases:
Enum
Describes the incident and scattered spin state of a polarised neutron beam.
- DOWN_DOWN = (0, 0)
- DOWN_UP = (0, 1)
- UP_DOWN = (1, 0)
- UP_UP = (1, 1)
- class refnx.reduce.SpinSet(down_down, up_up, down_up=None, up_down=None)[source]
Bases:
object
Describes a set of spin-channels at a given angle of incidence, and can process beams with individual reduction options.
- Parameters
down_down (str or refnx.reduce.PlatypusNexus) – Input filename or PlatypusNexus object for the R– spin channel.
up_up (str or refnx.reduce.PlatypusNexus) – Input filename or PlatypusNexus object for the R++ spin channel.
down_up (str or refnx.reduce.PlatypusNexus, optional) – Input filename or PlatypusNexus object for the R-+ spin channel.
up_down (str or refnx.reduce.PlatypusNexus, optional) – Input filename or PlatypusNexus object for the R+- spin channel.
- channels
- Dictionary of each measured spin channel
“dd” : refnx.reduce.PlatypusNexus (R–) “du” : refnx.reduce.PlatypusNexus or None (R-+) “ud” : refnx.reduce.PlatypusNexus or None (R+-) “uu” : refnx.reduce.PlatypusNexus (R++)
- Type
- sc_opts
Reduction options for each spin channel (“dd”, “du”, “ud”, “uu)
- Type
- dd
R– spin channel
- uu
R++ spin channel
- du
R-+ spin channel
- Type
refnx.reduce.PlatypusNexus or None
- ud
R+- spin channel
- Type
refnx.reduce.PlatypusNexus or None
Notes
Each of the ReductionOptions specified in dd_opts, etc, is used to specify the options used to reduce each spin channel. The following reduction options must be consistent and identical across all spin channels so as to maintain the same wavelength axis across the datasets:
lo_wavelength : key in refnx.reduce.ReductionOptions hi_wavelength : key in refnx.reduce.ReductionOptions rebin_percent : key in refnx.reduce.ReductionOptions wavelength_bins : key in refnx.reduce.ReductionOptions
- property dd
- property du
- plot_spectra(**kwargs)[source]
Plots the processed spectrums for each spin state in the SpinSet
Requires matplotlib to be installed
- process(**reduction_options)[source]
Process beams in SpinSet.
If reduction_options is None, the reduction options for each spin channel are specified by the dictionary of spin channel reduction options SpinSet.sc_opts which are initialised to the standard options when constructing the object.
If you wish to have unique reduction options for each spin channel, you need to ensure that the wavelength bins between each spin channel remain identical, otherwise a ValueError will be raised.
If reduction_options is not None, then SpinSet.process() will use these options for all spin channels.
- Parameters
reduction_options (dict, optional) – A single dict of options used to process all spectra.
- property spin_channels
Gives a quick indication of what spin channels were measured and are present in this SpinSet.
- Returns
list of refnx.reduce.SpinChannel Enum values or None, depending on
if the spin channel was measured.
- property ud
- property uu
- refnx.reduce.accumulate_HDF_files(files)[source]
Accumulates HDF files together, writing an accumulated file in the current directory. The accumulated datafile is written in the current directory (os.getcwd()) and has a filename based on the first file, prepended by ‘ADD_’. For example, if the first file is PLP0000708.nx.hdf then the accumulated file is ADD_PLP0000708.nx.hdf.
- Parameters
files (list) – Strings specifying NeXUS filenames to be added together.
- refnx.reduce.basename_datafile(pth)[source]
Given a NeXUS path return the basename minus the file extension. :param pth: :type pth: str
- Returns
basename
- Return type
Examples
>>> basename_datafile('a/b/c.nx.hdf') 'c'
- refnx.reduce.catalogue(start, stop, data_folder=None, prefix='PLP', keys=None)[source]
Extract interesting information from Platypus NeXUS files.
- Parameters
start (int) – start cataloguing from this run number
stop (int) – stop cataloguing at this run number
data_folder ({str, Path}, optional) – path specifying location of NeXUS files
prefix ({'PLP', 'SPZ'}, optional) – str specifying whether you want to catalogue Platypus or Spatz files
keys (sequence of str, optional) – specifies the keys to be extracted from each catalogue. Overrides the default set of keys.
- Returns
catalog – Dataframe containing interesting parameters from Platypus Nexus files
- Return type
pd.DataFrame
Notes
The default set of keys is: [“filename”, “end_time”, “sample_name”, “ss1vg”, “ss2vg”, “ss3vg”,
“ss4vg”, “omega”, “twotheta”, “total_counts”, “bm1_counts”, “time”, “daq_dirname”, “start_time”]
- refnx.reduce.create_reflect_nexus(h5data)[source]
Creates a ReflectNexus object from an HDF file
- Parameters
h5data ({ReflectNexus, HDF5 NeXus file, str, Path}) – A ReflectNexus object, an HDF5 NeXus file for Platypus/Spatz, or a str/Path specifying the path to one
- refnx.reduce.datafile_number(fname, prefix='PLP')[source]
From a filename figure out what the run number was
- Parameters
fname (str) – The filename to be processed
- Returns
run_number – The run number
- Return type
Examples
>>> datafile_number('PLP0000708.nx.hdf') 708
- refnx.reduce.number_datafile(run_number, prefix='PLP')[source]
Given a run number figure out what the file name is. Given a file name, return the filename with the .nx.hdf extension
- Parameters
- Returns
file_name
- Return type
Examples
>>> number_datafile(708) 'PLP0000708.nx.hdf' >>> number_datafile(708, prefix='QKK') 'QKK0000708.nx.hdf' >>> number_datafile('PLP0000708.nx.hdf') 'PLP0000708.nx.hdf'
- refnx.reduce.reduce_stitch(reflect_list, direct_list, data_folder=None, prefix='PLP', trim_trailing=True, save=True, scale=1.0, reduction_options=None)[source]
Reduces a list of reflected beam run numbers and a list of corresponding direct beam run numbers from the Platypus/Spatz reflectometers. If there are multiple reflectivity files they are spliced together.
- Parameters
reflect_list (list) – Reflected beam run numbers, e.g. [708, 709, 710] 708 corresponds to the file PLP0000708.nx.hdf.
direct_list (list) – Direct beam run numbers, e.g. [711, 711, 711]
data_folder ({str, Path}, optional) – Where is the raw data stored?
prefix (str, optional) – The instrument filename prefix.
trim_trailing (bool, optional) – When datasets are spliced together do you want to remove points in the overlap region from the preceding dataset?
save (bool, optional) – If True then the spliced file is written to a file (in the working directory) with a name like: c_PLP0000708.dat.
scale (float, optional) – Scales the data by this value.
reduction_options (None, dict, or list of dict, optional) – Options passed directly to refnx.reduce.PlatypusNexus.process, for processing of individual spectra. Look at that method docstring for specification of options. If an individual dict then the same options are used to process all datasets. A list (or sequence) of dict can be used to specify different options for each datasets. If None, then a default set of reduction options will be used.
- Returns
combined_dataset, reduced_filename – The combined dataset and the file name of the reduced data, if it was saved. If it wasn’t saved reduced_filename is None.
- Return type
Notes
The prefix is used to specify the run numbers to a filename. For example a run number of 10, and a prefix of PLP resolves to a NeXus filename of ‘PLP0000010.nx.hdf’.
Examples
>>> from refnx.reduce import reduce_stitch >>> dataset, fname = reduce_stitch([708, 709, 710], ... [711, 711, 711], ... reduction_options={"rebin_percent": 2})
- refnx.reduce.reduce_xrdml(f, bkg=None, scale=None, sample_length=None)[source]
Reduces a Panalytical XRDML file
- Parameters
f (file-like object or string) – The specular reflectivity (XRDML) file of interest
bkg (list) – A list of file-like objects or strings that contain background measurements. The background is assumed to have the same number of points as the specular reflectivity curve. The backgrounds are averaged and subtracted from the specular reflectivity
scale (float, None) – The direct beam intensity (cps). If scale is None then the dataset is scaled by the point with maximum intensity below Q = 0.0318 (Q_crit for Si at 8.048 keV).
sample_length (None or float) – If None then no footprint correction is done. Otherwise the transverse footprint of the sample (mm).
- Returns
dataset – The specular reflectivity as a function of momentum transfer, Q.
- Return type