usansred package

usansred.io.read

usansred.io.read.config_from_csv(csv_path: str) → ReductionConfig

Reads the reduction configuration from a CSV file.

Returns

ReductionConfig

Validated reduction configuration.

usansred.io.read.config_from_json(json_path: str) → ReductionConfig

Reads the reduction configuration from a JSON file.

Returns

ReductionConfig

Validated reduction configuration.

usansred.io.read.read_config(file_path: str) → ReductionConfig

Wrapper function to read configuration from different file formats.

Parameters

file_path: str

Path to the reduction configuration file.

Returns

ReductionConfig

Validated reduction configuration.

usansred.io.save

Utility functions for USANS reduction. As we add utilities, perhaps we can split them into separater modules

usansred.io.save.save_ascii(input_workspace, file_path, header=None, **saveascii)

Save a workspace to an ASCII file.

Parameters

input_workspacestr or Workspace

Input workspace to be summed before saving.

file_pathstr or path-like

Destination file path for the ASCII output.

headerstr, optional

Header text to insert or replace in the output file. If provided, and it does not start with #, it is prefixed with #.

saveasciikwargs

Additional keyword arguments passed through to mantid.simpleapi.SaveAscii. If argument WriteSpectrumID is not supplied, it defaults to False.

usansred.io.save.save_summed_spectra(input_workspace, file_path, header=None)

Save the summed spectra of a workspace to an ASCII file.

Parameters

input_workspacestr or Workspace

Input workspace to be summed before saving.

file_pathstr or path-like

Destination file path for the ASCII output.

headerstr, optional

Header text to insert or replace in the output file. If provided, and it does not start with #, it is prefixed with #.

usansred.model

usansred.reduce

class usansred.reduce.CombinedSample(**data: Any)

Bases: BaseModel

Combine multiple Sample measurements at the raw (X,Y,E) scan level before converting to (Q,I,E).

Attributes

namestr

Combined sample name.

experimentExperiment

Experiment this combined sample belongs to.

thicknessfloat

Sample thickness in cm.

measurement_typeMeasurementType

Type of measurement (sample, background, or empty cell).

combined_sampleslist[Sample]

Individual Sample objects whose scans will be combined.

combined_scanslist[Scan]

Scans produced by the combination.

combine() → None

Sum raw XY data from all combined samples scan-by-scan, then generate IQ data.

For each scan index, the monitor and detector XY data from every sample are accumulated. If a sample has fewer scans than others a warning is logged and it is skipped for that index. After accumulation the XY to IQ conversion is performed on the combined data and ready for reduction.

Raises

AssertionError

If combined_samples is empty or none of them contain scans.

combined_samples: list[Sample]

combined_scans: list[Scan]

experiment: Experiment

measurement_type: MeasurementType

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

thickness: float

class usansred.reduce.Experiment(*, config_file: str, output_dir: str = '', prim_wave: float = 3.6, v_angle: float = 0.042, log_binning: bool = False, num_of_banks: int = 4, folder: str = '', samples: list[~usansred.reduce.Sample] = <factory>, background: ~usansred.reduce.Sample | None = None, empty_cell: ~usansred.reduce.Sample | None = None)

Bases: BaseModel

Experiment configuration for USANS data reduction

Attributes

config_filestr

Path to the configuration file

_configReductionConfig

Validated reduction configuration, always set after construction (private attribute)

output_dirstr | None

Output folder for reduced data, default is current folder

prim_wavefloat

Primary wavelength in Angstroms, default is 3.6

v_anglefloat

Vertical angle, default is 0.042

log_binningbool

Flag for log-binning, default is False

num_of_banksint

Number of detector banks, default is 4 (not expected to change)

folderstr

Working folder for this experiment, derived from config file path (private attribute)

sampleslist[Sample]

List of samples, populated from config file (private attribute)

backgroundSample | None

Background sample, populated from config file if specified (private attribute)

empty_cellSample | None

Empty cell sample, populated from config file if specified (private attribute)

amend_log_binning(logbin: bool) → None

Override the log-binning setting with the command-line –logbin flag.

For backwards compatibility when user enters a CSV file

Parameters

logbinbool

When True, enables log-binning regardless of what the config file says. When False, the config-file value set during initialisation is preserved.

background: Sample | None

property config: ReductionConfig

Validated reduction configuration, always set after construction.

config_file: str

dump_reduced_data()

Dump reduced data to txt files

empty_cell: Sample | None

folder: str

log_binning: bool

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_context: Any) → None

Post-validation initializer

num_of_banks: int

output_dir: str

prim_wave: float

reduce(output_dir: str | None = None)

Reduce the USANS data

Parameters

output_dir: str | None

The result will be dumped to the output folder. If none will just use current folder

samples: list[Sample]

v_angle: float

class usansred.reduce.Sample(**data: Any)

Bases: BaseModel

Container for sample information, related scans, and data reduction methods

property config

counts: EventCounts

property data

Main detector data, currently an alias for detector_data[0]

data_bg_subtracted: IQData

data_log_binned: IQData

property data_reduced

Reduced data, currently an alias for bg_subtracted data

data_scaled: list[IQData]

detector_data: list[IQData]

dump_data_to_csv(filepath: str, data: IQData | XYData, title: str | None = None)

Dump IQ or XY data to a CSV file.

dump_reduced_data_to_csv(detector_data: bool = True, scaled_data: bool = True, bg_subtracted_data: bool = True, log_binned_data: bool = True)

Dump reduced data to CSV files based on specified flags.

exclude: list[int]

experiment: Experiment

property is_log_binned: bool

Flag to indicate if the sample has been log-binned

property is_reduced: bool

Flag to indicate if the sample has been reduced

log_bin_data(data: IQData) → IQData

Log-bin the I(Q) data.

measurement_type: MeasurementType

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_context: Any) → None

Post-validation initializer

name: str

normalize_by_monitor() → None

Normalize detector intensities by monitor counts for all scans.

property num_log_bins: int

Size of the log-binned data

property num_of_banks: int

Number of detector banks in the Experiment

num_of_scans: int

reduce()

Reduce this sample’s scans

rescale_data() → None

Rescale reflected data by the analyzer’s solid angle acceptance and by sample thickness.

rocking_curve_centering() → float

Center the stitched rocking curves by fitting a Gaussian peak to the rocking curve of the first harmonic.

Notice that the q values of the stitched rocking curves are analyzer motor angles at this stage of reduction, not yet converted to Q values. The first harmonic is fit to a Gaussian over the mostly symmetric angle range [q_min, -q_min], where q_min is the minimum analyzier motor angle. It will be a negative value. The center of the fitted Gaussian represents the value of the analyzer motor angle at which the analyzer reflects neutrons that have not been scattered by the sample. It should be very close to zero.

Returns

float

Fitted first-harmonic motor-angle center.

scans: list[Scan]

property size: int

Number of detector data points

property size_reduced: int

Number of reduced data points

start_scan_num: int

stitch_scans()

Stitch scan data from each detector bank into per-bank intensity curves.

For each detector bank (harmonic), combine all scans in self.scans onto a single Intensity-versus-Q profile. Detector intensities and errors are expected to already be normalized by Scan.normalize_by_monitor before being added to the stitched output.

Notice that at this stage, the “Q” values are actually analyzer-motor angles, that is, detector bank iq_data.q values are analyzer-motor angles (in arcsec units).

If two or more scans contain the same “Q” value, their intensities are combined into one point using inverse-variance weighting, and the combined uncertainty is stored as the square root of the inverse summed weights.

After all scans for a bank are processed, the stitched points are sorted by Q

The method also generates log messages for the raw scan theta ranges and converted Q ranges in 1/angstrom for the first detector bank. Results are stored on self.detector_data; no value is returned.

subtract_background(background: Sample) → None

Subtract background data from this sample’s data.

Parameters

backgroundSample

The background sample to subtract. Must be processed (stitched, scaled, and binned).

thickness: float

transmission: float

transmitted: float

class usansred.reduce.Scan(**data: Any)

Bases: BaseModel

A single scan (run) of a sample in an experiment

Attributes

numberint

Scan (run) number

countsEventCounts

Event counts object for this scan

experimentExperiment

Experiment this scan belongs to

monitor_dataMonitorData

Monitor data associated with this scan

detector_datalist[MonitorData]

Detector data associated with this scan

load_databool

Whether to load data files during initialization. Set to False when creating placeholder scans (e.g. for CombinedSample).

convert_xy_to_iq(xy_data: XYData) → IQData

Convert XY data to IQ data

Directly copies x to q, y to i, and t. For error, calculates based on a Poisson-like statistical model: err = sqrt(|y - 0.5| + 0.5) which ensures a minimum value to avoid zero error for low counts.

counts: EventCounts

detector_data: list[MonitorData]

experiment: Experiment

load()

Load data files for this scan.

load_data: bool

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(_context: Any) → None

Post-validation initializer

monitor_data: MonitorData

normalize_by_monitor() → None

Normalize detector intensities by monitor counts.

Each harmonic in the scan is normalized independently, and within each harmonic, the counts collected at the detector during the time the analyzer-motor remained at a particular angle are divided by the counts collected at the monitor during such time.

property num_of_banks: int

Number of detector banks in the Experiment

number: int

read_xy_file(filepath: str) → XYData

Read XY data from a file

property size: int

Number of data points

usansred.reduce.horizontal_rocking_width(order: int) → float

FWHM (arcs) of the resolution function at the detector for a given reflection order

References

M. Agamalian et al., “Progress on The Time-of-Flight Ultra Small Angle Neutron Scattering Instrument at SNS”, J. Phys.: Conf. Ser. 1021 (2018) 012033.

Parameters

orderint

Positive reflection order (a.k.a. harmonic or bank)

Returns

float

Computed horizontal angular resolution.

usansred.reduce.main()

Main function to run USANS data reduction

usansred.reduce.parse_args()

usansred.reduce_USANS

usansred.reduce_USANS.get_sequence_info(seq_file)

Get the sequence information from local autoreduce folder json files for autoreduction

usansred.reduce_USANS.main()

usansred.reduce_USANS.update_sequence_info(out_file, info)

usansred.summary

summary.py: summary of the reduced data.

usansred.summary.generate_report(config_file_path: str, data_dir: str | None = None, output_dir: str | None = None)

Generate report from a reduction config file.

Parameters

config_file_pathstr

Path to the configuration file (CSV or JSON).

data_dirstr | None

Directory where the reduced data are stored. If None, use the reduced dir in the config file directory.

output_dirstr | None

Where to save the report. If None, use data_folder/reduced.

usansred.utils

usansred.utils.cast_to_bool(value: Any) → bool

Convert common setup-file values to a boolean.