Capillary sample and container attenuation correction

Summary

Subtract empty-capillary wall scattering on its filled-capillary attenuation scale, then correct sample-origin attenuation.

Metadata

• Import path: modacor.modules.technique_modules.scattering.capillary_sample_container_correction.CapillarySampleContainerCorrection

• Source: src/modacor/modules/technique_modules/scattering/capillary_sample_container_correction.py

• Module ID: CapillarySampleContainerCorrection

• Module version: 20260906.3

• Keywords: sample, container, capillary, absorption, subtraction

Required data keys

• signal

• coord_x

• coord_y

• coord_z

Modifies

• signal: signal, uncertainties

• mask: signal

• capillary_sample_attenuation: signal, uncertainties

• capillary_wall_attenuation_filled: signal, uncertainties

• capillary_wall_attenuation_empty: signal

• capillary_wall_subtraction_scale: signal, uncertainties

• capillary_filled_calculated_transmission: signal, uncertainties

• capillary_empty_calculated_transmission: signal

• capillary_effective_sample_mu: signal, uncertainties

• capillary_beam_profile_retained_fraction: signal

• capillary_sample_attenuation_evaluated: signal

• capillary_wall_filled_attenuation_evaluated: signal

• capillary_wall_empty_attenuation_evaluated: signal

Required arguments

• beam_profile

• filled_processing_key

• empty_processing_key

Default configuration

{
  "absolute_tolerance": 1e-12,
  "beam_profile": null,
  "capillary_axis": [
    1.0,
    0.0,
    0.0
  ],
  "capillary_centre": [
    0.0,
    0.0,
    0.0
  ],
  "capillary_centre_units": "m",
  "chord_order": 12,
  "coord_x_key": "coord_x",
  "coord_y_key": "coord_y",
  "coord_z_key": "coord_z",
  "detector_chunk_size": 256,
  "effective_sample_mu_key": "capillary_effective_sample_mu",
  "empty_calculated_transmission_key": "capillary_empty_calculated_transmission",
  "empty_centre_mu": 0.0,
  "empty_centre_mu_source": null,
  "empty_centre_mu_units": "1/m",
  "empty_centre_mu_units_source": null,
  "empty_mask_key": null,
  "empty_processing_key": "background",
  "evaluation_mode": "adaptive",
  "filled_calculated_transmission_key": "capillary_filled_calculated_transmission",
  "filled_processing_key": "sample",
  "incident_direction": [
    0.0,
    0.0,
    1.0
  ],
  "mask_key": "mask",
  "max_depth": 10,
  "minimum_attenuation_factor": 1e-12,
  "profile_retained_fraction_key": "capillary_beam_profile_retained_fraction",
  "relative_tolerance": 0.001,
  "sample_attenuation_key": "capillary_sample_attenuation",
  "sample_evaluated_mask_key": "capillary_sample_attenuation_evaluated",
  "sample_mu": null,
  "sample_mu_sensitivity_relative_step": 0.01,
  "sample_mu_source": null,
  "sample_mu_units": "1/m",
  "sample_mu_units_source": null,
  "sample_phase_absorption": null,
  "sample_phase_absorption_source": null,
  "sample_phase_absorption_uncertainties_sources": {},
  "sample_phase_thickness": null,
  "sample_phase_thickness_source": null,
  "sample_phase_thickness_uncertainties_sources": {},
  "sample_phase_thickness_units": "m",
  "sample_phase_thickness_units_source": null,
  "sample_phase_transmission": null,
  "sample_phase_transmission_source": null,
  "sample_phase_transmission_uncertainties_sources": {},
  "sample_radius": null,
  "sample_radius_source": null,
  "sample_radius_units": "m",
  "sample_radius_units_source": null,
  "wall_chord_order": null,
  "wall_empty_attenuation_key": "capillary_wall_attenuation_empty",
  "wall_empty_evaluated_mask_key": "capillary_wall_empty_attenuation_evaluated",
  "wall_filled_attenuation_key": "capillary_wall_attenuation_filled",
  "wall_filled_evaluated_mask_key": "capillary_wall_filled_attenuation_evaluated",
  "wall_mu": 0.0,
  "wall_mu_source": null,
  "wall_mu_units": "1/m",
  "wall_mu_units_source": null,
  "wall_subtraction_scale_key": "capillary_wall_subtraction_scale",
  "wall_thickness": 0.0,
  "wall_thickness_source": null,
  "wall_thickness_units": "m",
  "wall_thickness_units_source": null
}

Argument specification

Argument	Type	Required	Default	Dependency role	Description
absolute_tolerance	int or float	No	1e-12	-	Adaptive absolute tolerance.
beam_profile	dict	Yes	-	-	Measured-image, gaussian_2d, or trapezoid_2d beam-profile configuration.
capillary_axis	tuple	No	[1.0, 0.0, 0.0]	-	Capillary centreline direction in the lab frame; horizontal by default.
capillary_centre	tuple	No	[0.0, 0.0, 0.0]	-	Point on the capillary centreline in capillary_centre_units.
capillary_centre_units	str	No	m	-	Capillary-centre length units.
chord_order	int	No	12	-	Gauss–Legendre nodes per occupied chord.
coord_x_key	str	No	coord_x	-	Detector lab x-coordinate key.
coord_y_key	str	No	coord_y	-	Detector lab y-coordinate key.
coord_z_key	str	No	coord_z	-	Detector lab z-coordinate key.
detector_chunk_size	int	No	256	-	Expert detector chunk-size override.
effective_sample_mu_key	str	No	capillary_effective_sample_mu	-	Resolved or derived effective sample attenuation-coefficient key.
empty_calculated_transmission_key	str	No	capillary_empty_calculated_transmission	-	Output key for calculated empty-capillary transmission.
empty_centre_mu	int or float or NoneType	No	0.0	-	Linear attenuation coefficient inside the nominally empty capillary.
empty_centre_mu_source	str or NoneType	No	-	-	Optional IoSources reference for empty-centre attenuation.
empty_centre_mu_units	str	No	1/m	-	Empty-centre-mu reciprocal-length units.
empty_centre_mu_units_source	str or NoneType	No	-	-	Optional IoSources reference for empty-centre-mu units.
empty_mask_key	str or NoneType	No	-	-	Empty-capillary mask key; defaults to mask_key.
empty_processing_key	str	Yes	background	-	DataBundle containing the matching empty-capillary measurement.
evaluation_mode	str	No	adaptive	-	Adaptive detector-grid interpolation or exact active-pixel point rays.
filled_calculated_transmission_key	str	No	capillary_filled_calculated_transmission	-	Output key for calculated filled-capillary transmission.
filled_processing_key	str	Yes	sample	-	DataBundle containing the filled-capillary measurement and output signal.
incident_direction	tuple	No	[0.0, 0.0, 1.0]	-	Incident beam propagation direction in the lab frame.
mask_key	str or NoneType	No	mask	-	Optional boolean mask key; True pixels are inactive and retain identity factors.
max_depth	int	No	10	-	Maximum adaptive subdivision depth.
minimum_attenuation_factor	int or float	No	1e-12	-	Minimum allowed active-pixel attenuation divisor.
profile_retained_fraction_key	str	No	capillary_beam_profile_retained_fraction	-	Output key for retained beam-profile incident weight.
relative_tolerance	int or float	No	0.001	-	Adaptive relative tolerance.
sample_attenuation_key	str	No	capillary_sample_attenuation	-	Output key for A_s,sc.
sample_evaluated_mask_key	str	No	capillary_sample_attenuation_evaluated	-	Exact-evaluation mask for A_s,sc.
sample_mu	int or float or NoneType	No	-	-	Sample linear attenuation coefficient; alternatively use its source or phase-factor inputs.
sample_mu_sensitivity_relative_step	int or float	No	0.01	-	Relative finite-difference step for derived-sample-mu uncertainty propagation.
sample_mu_source	str or NoneType	No	-	-	Optional IoSources reference for sample linear attenuation coefficient.
sample_mu_units	str	No	1/m	-	Sample-mu reciprocal-length units.
sample_mu_units_source	str or NoneType	No	-	-	Optional IoSources reference for sample-mu units.
sample_phase_absorption	int or float or NoneType	No	-	-	Sample-only absorbed fraction A=1-T; use with sample_phase_thickness instead of sample_mu.
sample_phase_absorption_source	str or NoneType	No	-	-	Optional IoSources reference for the dimensionless sample-only absorbed fraction.
sample_phase_absorption_uncertainties_sources	dict	No	{}	-	Uncertainty-name to IoSources-reference mapping for sample-only absorption.
sample_phase_thickness	int or float or NoneType	No	-	-	Transmission path thickness used to derive effective sample mu.
sample_phase_thickness_source	str or NoneType	No	-	-	Optional IoSources reference for the sample-phase transmission path thickness.
sample_phase_thickness_uncertainties_sources	dict	No	{}	-	Uncertainty-name to IoSources-reference mapping for sample-phase thickness.
sample_phase_thickness_units	str	No	m	-	Sample-phase transmission path-thickness units.
sample_phase_thickness_units_source	str or NoneType	No	-	-	Optional IoSources reference for sample-phase thickness units.
sample_phase_transmission	int or float or NoneType	No	-	-	Sample-only transmission T; use with sample_phase_thickness instead of sample_mu.
sample_phase_transmission_source	str or NoneType	No	-	-	Optional IoSources reference for the dimensionless sample-only transmission.
sample_phase_transmission_uncertainties_sources	dict	No	{}	-	Uncertainty-name to IoSources-reference mapping for sample-only transmission.
sample_radius	int or float or NoneType	No	-	-	Inner/sample radius; alternatively use sample_radius_source.
sample_radius_source	str or NoneType	No	-	-	Optional IoSources reference for sample radius.
sample_radius_units	str	No	m	-	Sample-radius units.
sample_radius_units_source	str or NoneType	No	-	-	Optional IoSources reference for sample-radius units.
wall_chord_order	int or NoneType	No	-	-	Wall-origin nodes per occupied chord; defaults to chord_order.
wall_empty_attenuation_key	str	No	capillary_wall_attenuation_empty	-	Output key for A_c,c.
wall_empty_evaluated_mask_key	str	No	capillary_wall_empty_attenuation_evaluated	-	Exact-evaluation mask for A_c,c.
wall_filled_attenuation_key	str	No	capillary_wall_attenuation_filled	-	Output key for A_c,sc.
wall_filled_evaluated_mask_key	str	No	capillary_wall_filled_attenuation_evaluated	-	Exact-evaluation mask for A_c,sc.
wall_mu	int or float or NoneType	No	0.0	-	Wall linear attenuation coefficient; zero is allowed for limit checks.
wall_mu_source	str or NoneType	No	-	-	Optional IoSources reference for wall linear attenuation coefficient.
wall_mu_units	str	No	1/m	-	Wall-mu reciprocal-length units.
wall_mu_units_source	str or NoneType	No	-	-	Optional IoSources reference for wall-mu units.
wall_subtraction_scale_key	str	No	capillary_wall_subtraction_scale	-	Output key for A_c,sc/A_c,c.
wall_thickness	int or float or NoneType	No	0.0	-	Capillary wall thickness, separate from sample radius.
wall_thickness_source	str or NoneType	No	-	-	Optional IoSources reference for wall thickness.
wall_thickness_units	str	No	m	-	Wall-thickness units.
wall_thickness_units_source	str or NoneType	No	-	-	Optional IoSources reference for wall-thickness units.

References

https://doi.org/10.1107/S0021889810021114

Notes

The filled and empty signals must already have comparable exposure and incident-flux normalization. Do not include a separate normalization by measured sample or empty-capillary transmission in the same correction pipeline. The operation is [F - (A_c,sc/A_c,c) E] / A_s,sc.