usansred package

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.

is_backgroundbool

Whether this combined sample represents a background measurement.

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

is_background: bool

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, config: dict = <factory>, output_dir: str = '', prim_wave: float = 3.6, v_angle: float = 0.042, log_binning: bool = False, num_of_banks: int = 4, folder: str = '', background: ~usansred.reduce.Sample | None = None, samples: list[~usansred.reduce.Sample] = <factory>)

Bases: BaseModel

Experiment configuration for USANS data reduction

Attributes

config_filestr

Path to the configuration file

configdict

Configuration file loaded into a Python dictionary. Populated for both JSON and CSV config files

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

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

config: dict

config_file: str

dump_reduced_data()

Dump reduced data to txt files

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

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

is_background: bool

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.

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

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

Bases: BaseModel

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

Attributes

numberint

Scan (run) number

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.

detector_data: list[MonitorData]

experiment: Experiment

load()

Load experiment data files

load_data: bool

load_detector_data()

load_monitor_data()

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.