\(\renewcommand\AA{\unicode{x212B}}\)
Table of Contents
The SumSpectra algorithm adds the data values in each time bin across a range of spectra; the output workspace has a single spectrum. If the input is an EventWorkspace, the output is also an EventWorkspace; otherwise it will be a Workspace2D.
Name | Direction | Type | Default | Description |
---|---|---|---|---|
InputWorkspace | Input | MatrixWorkspace | Mandatory | The workspace containing the spectra to be summed. |
OutputWorkspace | Output | MatrixWorkspace | Mandatory | The name of the workspace to be created as the output of the algorithm. A workspace of this name will be created and stored in the Analysis Data Service. |
StartWorkspaceIndex | Input | number | 0 | The first Workspace index to be included in the summing |
EndWorkspaceIndex | Input | number | Optional | The last Workspace index to be included in the summing |
ListOfWorkspaceIndices | Input | int list | A list of workspace indices as a string with ranges, for example: 5-10,15,20-23. Optional: if not specified, then the Start/EndWorkspaceIndex fields are used alone. If specified, the range and the list are combined (without duplicating indices). For example, a range of 10 to 20 and a list ‘12,15,26,28’ gives ‘10-20,26,28’. | |
IncludeMonitors | Input | boolean | True | Whether to include monitor spectra in the summation. |
WeightedSum | Input | boolean | False | Instead of the usual spectra sum, calculate the weighted sum. This has the form: \(nSpectra \times\Sigma(Signal_i/Error_i^2)/\Sigma(1/Error_i^2)\) This property is ignored for event workspace. The sums are defined for \(Error_i != 0\) only, so the values with zero error are dropped from the summation. To estimate the number of dropped values see the description. |
RemoveSpecialValues | Input | boolean | False | If enabled floating point special values such as NaN or Inf are removed before the spectra are summed. |
MultiplyBySpectra | Input | boolean | True | For unnormalized data one should multiply the weighted sum by the number of spectra contributing to the bin. |
UseFractionalArea | Input | boolean | True | Normalize the output workspace to the fractional area for RebinnedOutput workspaces. |
Takes a workspace as input and sums all of the spectra within it maintaining the existing bin structure and units. Any masked spectra are ignored. The result is stored as a new workspace containing a single spectra.
If we define a the \(i^{th}\) spectrum with bins \(j\). The unweighted sum is just (WeightedSum=False
)
The weighted sum (WeightedSum=True
and MultiplyBySpectra=True
, ignored for event workspaces), the sum is defined (skipping \(Signal_i[j]\) when \(Error_i[j] == 0\)),
\(NSpectra\) is the number of spectra contributing to that bin. If the weights contributing to the sum are equal, these result in the same value. This should be used for unnormalized (e.g. not divided by vanadium spectrum) data. If the data has been normalized (e.g. divided by vanadium spectrum for total scattering) then multiplying by the number of spectra contributing to the bin is incorrect, use WeightedSum=True
and MultiplyBySpectra=False
to sum as
The algorithm adds to the OutputWorkspace
three additional
properties (Log values). The properties (Log) names are:
NumAllSpectra
is the number of spectra contributed to the sumNumMaskSpectra
is the spectra dropped from the summations because they are masked. Monitors are not included in this total if IncludeMonitors=False
.NumZeroSpectra
is the number of zero bins in histogram workspace or empty spectra for event workspace. These spectra are dropped from the summation of histogram workspace when WeightedSum=True
.Assuming pWS
is the output workspace handle, from Python these
properties can be accessed using:
nSpectra = pWS.getRun().getLogData("NumAllSpectra").value
nMaskedSpectra = pWS.getRun().getLogData("NumMaskSpectra").value
nZeroSpectra = pWS.getRun().getLogData("NumZeroSpectra").value
Example - a simple example of running SumSpectra.
ws = CreateSampleWorkspace("Histogram", Random=True)
print("Workspace has %d spectra" % ws.getNumberHistograms())
ws = SumSpectra(ws)
print("Workspace has %d spectra" % ws.getNumberHistograms())
Output:
Workspace has 200 spectra
Workspace has 1 spectra
Example - running SumSpectra with a list of indices.
ws = CreateSampleWorkspace("Histogram", Random=True)
print("Workspace has %d spectra" % ws.getNumberHistograms())
ws = SumSpectra(ws, ListOfWorkspaceIndices='0-3, 10-13')
print("Workspace has %d spectra" % ws.getNumberHistograms())
Output:
Workspace has 200 spectra
Workspace has 1 spectra
Example - a running SumSpectra with a start and end index.
ws = CreateSampleWorkspace("Histogram", Random=True)
print("Workspace has %d spectra" % ws.getNumberHistograms())
ws = SumSpectra(ws, StartWorkspaceIndex=0, EndWorkspaceIndex=9)
print("Workspace has %d spectra" % ws.getNumberHistograms())
Output:
Workspace has 200 spectra
Workspace has 1 spectra
Example - a running SumSpectra in weighted sum mode.
ws = CreateSampleWorkspace("Histogram", Random=True)
print("Workspace has %d spectra" % ws.getNumberHistograms())
ws = SumSpectra(ws, WeightedSum=True)
print("Workspace has %d spectra" % ws.getNumberHistograms())
Output:
Workspace has 200 spectra
Workspace has 1 spectra
Categories: AlgorithmIndex | Transforms\Grouping
C++ header: SumSpectra.h (last modified: 2021-03-31)
C++ source: SumSpectra.cpp (last modified: 2021-03-31)