Make empty can subtraction optional

Author: jl-wynen

docs/user-guide/dream/dream-powder-reduction.ipynb

@@ -94,7 +94,10 @@
     "workflow[DspacingBins] = sc.linspace(\"dspacing\", 0.3, 2.3434, 201, unit=\"angstrom\")\n",
     "\n",
     "# Do not mask any pixels / voxels:\n",
-    "workflow = powder.with_pixel_mask_filenames(workflow, [])"
+    "workflow = powder.with_pixel_mask_filenames(workflow, [])\n",
+    "\n",
+    "# Enable subtraction by an empty can measurement:\n",
+    "powder.correction.add_empty_can_subtraction(workflow)"
    ]
   },
   {

src/ess/powder/correction.py

@@ -157,13 +157,49 @@ def _normalize_by_vanadium(
     return normed
 
 
-def normalize_by_vanadium_dspacing(
+def normalize_by_vanadium_dspacing_removed_empty_can(
     data: BackgroundSubtractedData[SampleRun],
     vanadium: FocussedDataDspacing[VanadiumRun],
     uncertainty_broadcast_mode: UncertaintyBroadcastMode,
 ) -> IofDspacing:
     """
-    Normalize sample data by a vanadium measurement and return intensity vs d-spacing.
+    Normalize sample data by a vanadium measurement and return intensity vs. d-spacing.
+
+    Parameters
+    ----------
+    data:
+        Sample data where events from an empty can / empty instrument measurement
+        have been subtracted.
+    vanadium:
+        Vanadium data.
+    uncertainty_broadcast_mode:
+        Choose how uncertainties of vanadium are broadcast to the sample data.
+        Defaults to ``UncertaintyBroadcastMode.fail``.
+
+    Returns
+    -------
+    :
+        ``data / vanadium``.
+        May contain a mask "zero_vanadium" which is ``True``
+        for bins where vanadium is zero.
+
+    See also
+    --------
+    normalize_by_vanadium_dspacing:
+        The same function but using data where no empty can has been subtracted.
+    """
+    return IofDspacing(
+        _normalize_by_vanadium(data, vanadium, uncertainty_broadcast_mode)
+    )
+
+
+def normalize_by_vanadium_dspacing(
+    data: FocussedDataDspacing[SampleRun],
+    vanadium: FocussedDataDspacing[VanadiumRun],
+    uncertainty_broadcast_mode: UncertaintyBroadcastMode,
+) -> IofDspacing:
+    """
+    Normalize sample data by a vanadium measurement and return intensity vs. d-spacing.
 
     Parameters
     ----------
@@ -181,19 +217,62 @@ def normalize_by_vanadium_dspacing(
         ``data / vanadium``.
         May contain a mask "zero_vanadium" which is ``True``
         for bins where vanadium is zero.
+
+    See also
+    --------
+    normalize_by_vanadium_dspacing_removed_empty_can:
+        The same function but using data where events from an empty can /
+        empty instrument measurement have been subtracted.
     """
     return IofDspacing(
         _normalize_by_vanadium(data, vanadium, uncertainty_broadcast_mode)
     )
 
 
-def normalize_by_vanadium_dspacing_and_two_theta(
+def normalize_by_vanadium_dspacing_and_two_theta_removed_empty_can(
     data: BackgroundSubtractedDataTwoTheta[SampleRun],
     vanadium: FocussedDataDspacingTwoTheta[VanadiumRun],
     uncertainty_broadcast_mode: UncertaintyBroadcastMode,
 ) -> IofDspacingTwoTheta:
     """
-    Normalize sample data by a vanadium measurement and return intensity vs
+    Normalize sample data by a vanadium measurement and return intensity vs.
+    (d-spacing, 2theta).
+
+    Parameters
+    ----------
+    data:
+        Sample data where events from an empty can / empty instrument measurement
+        have been subtracted.
+    vanadium:
+        Vanadium data.
+    uncertainty_broadcast_mode:
+        Choose how uncertainties of vanadium are broadcast to the sample data.
+        Defaults to ``UncertaintyBroadcastMode.fail``.
+
+    Returns
+    -------
+    :
+        ``data / vanadium``.
+        May contain a mask "zero_vanadium" which is ``True``
+        for bins where vanadium is zero.
+
+    See also
+    --------
+    normalize_by_vanadium_dspacing_and_two_theta:
+        The same function but using data where no empty can has been subtracted.
+    """
+    return IofDspacingTwoTheta(
+        _normalize_by_vanadium(data, vanadium, uncertainty_broadcast_mode)
+    )
+
+
+def normalize_by_vanadium_dspacing_and_two_theta(
+    data: FocussedDataDspacingTwoTheta[SampleRun],
+    vanadium: FocussedDataDspacingTwoTheta[VanadiumRun],
+    uncertainty_broadcast_mode: UncertaintyBroadcastMode,
+) -> IofDspacingTwoTheta:
+    """
+    Normalize sample data by a vanadium measurement and return intensity vs.
     (d-spacing, 2theta).
 
     Parameters
@@ -212,6 +291,12 @@ def normalize_by_vanadium_dspacing_and_two_theta(
         ``data / vanadium``.
         May contain a mask "zero_vanadium" which is ``True``
         for bins where vanadium is zero.
+
+    See also
+    --------
+    normalize_by_vanadium_dspacing_and_two_theta_removed_empty_can:
+        The same function but using data where events from an empty can /
+        empty instrument measurement have been subtracted.
     """
     return IofDspacingTwoTheta(
         _normalize_by_vanadium(data, vanadium, uncertainty_broadcast_mode)
@@ -375,6 +460,12 @@ def insert_run_normalization(
             workflow.insert(normalize_by_proton_charge)
 
 
+def add_empty_can_subtraction(workflow: sciline.Pipeline) -> None:
+    """Insert providers to subtract empty can events from sample data."""
+    workflow.insert(normalize_by_vanadium_dspacing_removed_empty_can)
+    workflow.insert(normalize_by_vanadium_dspacing_and_two_theta_removed_empty_can)
+
+
 providers = (
     subtract_background,
     subtract_background_two_theta,

tests/dream/geant4_reduction_test.py

@@ -101,10 +101,16 @@ def params_for_det(request):
 
 
 @pytest.fixture
-def workflow(params_for_det):
+def workflow_no_empy_can(params_for_det):
     return make_workflow(params_for_det, run_norm=powder.RunNormalization.proton_charge)
 
 
+@pytest.fixture
+def workflow(workflow_no_empy_can):
+    powder.correction.add_empty_can_subtraction(workflow_no_empy_can)
+    return workflow_no_empy_can
+
+
 def make_workflow(params_for_det, *, run_norm):
     wf = dream.DreamGeant4Workflow(run_norm=run_norm)
     for key, value in params_for_det.items():
@@ -119,6 +125,15 @@ def test_pipeline_can_compute_dspacing_result(workflow):
     assert sc.identical(result.coords['dspacing'], params[DspacingBins])
 
 
+def test_pipeline_can_compute_dspacing_result_without_empty_can(workflow_no_empy_can):
+    workflow_no_empy_can[Filename[BackgroundRun]] = None
+    workflow_no_empy_can[MonitorFilename[BackgroundRun]] = None
+    workflow_no_empy_can = powder.with_pixel_mask_filenames(workflow_no_empy_can, [])
+    result = workflow_no_empy_can.compute(IofDspacing)
+    assert result.sizes == {'dspacing': len(params[DspacingBins]) - 1}
+    assert sc.identical(result.coords['dspacing'], params[DspacingBins])
+
+
 def test_pipeline_can_compute_dspacing_result_using_lookup_table_filename(workflow):
     workflow = powder.with_pixel_mask_filenames(workflow, [])
     workflow[TimeOfFlightLookupTableFilename] = dream.data.tof_lookup_table_high_flux()