$$\renewcommand\AA{\unicode{x212B}}$$

Summary¶

An algorithm to mask a detector, or set of detectors, as not to be used. The workspace spectra associated with those detectors are zeroed.

Properties¶

Name

Direction

Type

Default

Description

Workspace

InOut

Workspace

Mandatory

The name of the input and output workspace on which to perform the algorithm.

SpectraList

Input

int list

A list of spectra to mask

DetectorList

Input

int list

A list of detector ID’s to mask

WorkspaceIndexList

Input

unsigned int list

A list of the workspace indices to mask

Input

MatrixWorkspace

If given but not as a SpecialWorkspace2D, the masking from this workspace will be copied. If given as a SpecialWorkspace2D, the masking is read from its Y values.

Input

boolean

False

Works when ‘MaskedWorkspace’ is provided and forces to use spectra-detector mapping even in case when number of spectra in ‘Workspace’ and ‘MaskedWorkspace’ are equal

StartWorkspaceIndex

Input

number

0

If other masks fields are provided, it’s the first index of the target workspace to be allowed to be masked from by these masks, if not, its the first index of the target workspace to mask. Default value is 0 if other masking is present or ignored if not.

EndWorkspaceIndex

Input

number

Optional

If other masks are provided, it’s the last index of the target workspace allowed to be masked to by these masks, if not, its the last index of the target workspace to mask. Default is number of histograms in target workspace if other masks are present or ignored if not.

ComponentList

Input

str list

A list names of components to mask

Introduction¶

To understand the algorithms options, user should clearly understand the difference between WorkspaceIndex – the numbers, specified in WorkspaceIndexList and StartWorkspacIndex, EndWorkspaceIndex properties, the Spectra Number or according to other terminology Spectra ID – values of the SpectraList property and Detector ID – the numbers to provide for DetectorList property.

The WorkspaceIndex is the number a spectrum has in a workspace, e.g.

sp = ws.getSpectrum(0)


always returns first spectra present in the workspace.

The Spectra Number or spectra ID mean the number, assigned to a spectrum. This number is often equal to WorkspaceIndex+1, e.g.

print(sp.getSpectrumNo())


from the sample above will often print 1 but not always. The simplest case when this number is different is when you load a second half of a workspace, when the first spectrum number still is NumTotalSpectraInWorkspace/2+1, while WorkspaceIndex of this spectra becomes 0, i.e.:

sp = ws.getSpectrum(0)
print(sp.getSpectrumNo())


prints number equal to NumTotalSpectraInWorkspace/2+1. There are other ways to assign a random number to a spectrum.

And finally, the detector ID is the number assigned to a detector in an instrument definition file. Sometimes, a first detector corresponds to the first spectra of a workspace, but it is not in any way certain. For example the code:

ws = CreateSimulationWorkspace('MARI','-0.5,0.5,0.5')
sp = ws.getSpectrum(1)
print("{} {}".format(sp.getSpectrumNo(), sp.getDetectorIDs()))


Will print:

2 set(1102)


but any ISIS MARI workspace obtained from experiment will produce different sequence, e.g. something like:

5 set(4101)


Description¶

The algorithm zeroes the data in the spectra of the input workspace defined as masked. The detectors corresponding to the masked spectra are also flagged as masked (can be verified by the IDetector::isMasked() method).

The Workspace property specifies the workspace to mask while the other properties provide various ways to define the spectra and detectors to mask.

If Workspace is PeaksWorkspace, only the detectors listed are masked and the mask must be specified by a DetectorList or MaskedWorkspace.

All but the Workspace property are optional and at least one of them must be set. If several are set, the combination of them is used.

The set of spectra and detectors to be masked can be given as a list of either spectrum numbers, detector IDs, workspace indices, component names, or as a workspace index range.

The workspace index range (properties StartWorkspacIndex and EndWorkspaceIndex) changes its action depending on other masking properties being provided, namely:

• If a workspace index range is provided alone, all spectra within this range are masked.

• If a workspace index range is provided in combination with any other masking property, only the indexes in this range are masked.

The algorithm works differently depending on MaskedWorkspace property being a Mask Workspace (SpecialWorkspace2D object) or Matrix Workspace.

If source MaskedWorkspace is a Mask Workspace and the number of spectra in the source MaskedWorkspace is equal to number of spectra in the target Workspace, the spectra numbers of the MaskedWorkspace are used as source of masking information for the target workspace.

If the numbers of spectra in Workspace and MaskedWorkspace are different, the algorithm extracts list of masked detector IDS from source workspace and uses them to mask the corresponding spectra of the target workspace.

Setting property ForceInstrumentMasking to true forces algorithm to always use MaskedWorkspace detector IDs as the source of the masking information. If a detector is masked, then the corresponding detector will be masked in the input Workspace.

If the input MaskedWorkspace is a Matrix Workspace and the number of spectra in the source MaskedWorkspace is equal to the number of spectra in the target Workspace, then workspace indices of the source are used.

If the numbers of spectra in Workspace and MaskedWorkspace are different, the algorithm extracts list of detector IDS from source workspace and uses them to mask the corresponding spectra of the target workspace.

• If a pixel is masked, it means that the data from this pixel won’t be used. In the masking workspace the corresponding value is 1.

• If a pixel is NOT masked, it means that the data from this pixel will be used. In the masking workspace the corresponding value is 0.

• If masked workspace with a masked spectrum is applied to a target workspace with grouped detectors, and only one detector in the group of target workspace is masked, all target spectra, containing this detector become masked.

• Workspace indices

• Spectrum numbers

• Detector IDs

• Instrument components

• General MatrixWorkspace other than MaskWorkspace (In this case, the mask will be extracted from this workspace)

• Workspace index range specified by setting either StartWorkspacIndex or EndWorkspaceIndex to non-default value. Note: Setting EndWorkspaceIndex to a value exceeding the number of histograms in the target workspace would mask the entire workspace.

Rules¶

Here are the rules for input information for masking

1. At least one of the masking inputs must be specified.

2. Workspace indices and Spectra cannot be given at the same time.

3. MaskWorkspace and general MatrixWorkspace cannot be given at the same time.

4. When a general MatrixWorkspace is specified, then all detectors in a spectrum are treated as masked if the effective detector of that spectrum is masked.

5. The detectors found recursively in given instrument components are added to the list of detectors to mask. If multiple components with the same name exist, the first component found is masked.

1. workspace indices/spectra

2. detectors

3. MaskWorkspace /general MatrixWorkspace will be combined by the plus operation.

There are 2 operations to mask a detector and thus spectrum related

1. Set the detector in workspace’s instrument’s parameter map to masked.

2. Zero the data and clear the events associated with the spectrum with detectors that are masked.

Usage¶

Example 1: specifying spectrum numbers

import numpy as np

# Create a workspace containing some data.
ws = CreateSampleWorkspace()
# Mask two detectors by specifying numbers 1 and 3

# Check that spectra with spectrum numbers 1 and 3 are masked

# Get the 1st spectrum in the workspace
spec = ws.getSpectrum(0)
detid = spec.getDetectorIDs()[0]
print('Spectrum number is {}'.format(spec.getSpectrumNo()))
print('All counts in the spectrum are 0:    {}'.format(np.all( y == 0.0 )))

# Get the 2nd spectrum in the workspace
spec = ws.getSpectrum(1)
detid = spec.getDetectorIDs()[0]
print('Spectrum number is {}'.format(spec.getSpectrumNo()))
print('All counts in the spectrum are 0:    {}'.format(np.all( y == 0.0 )))

# Get the 3rd spectrum in the workspace
spec = ws.getSpectrum(2)
detid = spec.getDetectorIDs()[0]
print('Spectrum number is {}'.format(spec.getSpectrumNo()))
print('All counts in the spectrum are 0:    {}'.format(np.all( y == 0.0 )))

# Get the 4th spectrum in the workspace
spec = ws.getSpectrum(3)
detid = spec.getDetectorIDs()[0]
print('Spectrum number is {}'.format(spec.getSpectrumNo()))
print('All counts in the spectrum are 0:    {}'.format(np.all( y == 0.0 )))


Output:

Spectrum number is 1
Detector of this spectrum is masked: True
All counts in the spectrum are 0:    True
Spectrum number is 2
Detector of this spectrum is masked: False
All counts in the spectrum are 0:    False
Spectrum number is 3
Detector of this spectrum is masked: True
All counts in the spectrum are 0:    True
Spectrum number is 4
Detector of this spectrum is masked: False
All counts in the spectrum are 0:    False


Example 2: specifying detector IDs

# Create a workspace containing some data.
ws = CreateSampleWorkspace()
# Mask two detectors by specifying detector IDs 101 and 103

# Check that spectra with spectrum numbers 1 and 3 are masked

# Check the 1st detector
det = ws.getInstrument().getDetector(101)

# Check the 2nd detector
det = ws.getInstrument().getDetector(103)

# Check some other detectors
det = ws.getInstrument().getDetector(100)
det = ws.getInstrument().getDetector(102)
det = ws.getInstrument().getDetector(105)


Output:

Detector  101  is masked: True


Example 3: specifying workspace indices

# Create a workspace containing some data.
ws = CreateSampleWorkspace()
# Mask two detectors by specifying workspace indices 0 and 2

# Check that spectra with workspace indices 0 and 2 are masked

# Check the 1st spectrum
workspaceIndex = 0
det = ws.getDetector( workspaceIndex )

# Check the 2nd spectrum
workspaceIndex = 2
det = ws.getDetector( workspaceIndex )

# Check some other spectra
workspaceIndex = 1
det = ws.getDetector( workspaceIndex )
workspaceIndex = 3
det = ws.getDetector( workspaceIndex )
workspaceIndex = 4
det = ws.getDetector( workspaceIndex )


Output:

Detector in spectrum with workspace index  0  is masked: True
Detector in spectrum with workspace index  2  is masked: True
Detector in spectrum with workspace index  1  is masked: False
Detector in spectrum with workspace index  3  is masked: False
Detector in spectrum with workspace index  4  is masked: False


Example 4: specifying instrument components

# Create a workspace containing some data.
ws = CreateSampleWorkspace()
# Mask the column of detectors named 'bank1(x=3)' in bank1, and bank2 entirely.
# Unfortunately, individual detectors cannot be masked this way in the
# workspace created by CreateSampleWorkspace since their
# names contain a comma ',' which breaks the parsing of the component list.

# Define a helper function.
for i in range(detsBegin, detsEnd):
det = ws.getInstrument().getDetector(i)
break
print('Detectors from {0} to {1} are masked.'.format(detsBegin, detsEnd))
else:

# Check the detector column in bank1

# Check bank2


Output:

Detectors from 130 to 140 are masked.
Detectors from 200 to 300 are masked.


Example 5: specifying a masking workspace

# Create a masking workspace

# Create a intermediate workspace to help create the masking workspace
tmp = CreateSampleWorkspace()

print('')

# Create a data workspace
ws = CreateSampleWorkspace()

# Check masking of first 5 detectors
det = ws.getDetector(0)
det = ws.getDetector(1)
det = ws.getDetector(2)
det = ws.getDetector(3)
det = ws.getDetector(4)


Output:

A masking workspace has 1 spectrum



Example 6: specifying a masking range

# Create a data workspace
ws = CreateSampleWorkspace()

# Check masking of first 6 detectors
for ind in range(0,6):
det = ws.getDetector(ind)


Output:

Detector 100 is masked: False


Example 7: constraining the masking range

# Create a masking workspace

# Create a intermediate workspace to help create the masking workspace
tmp = CreateSampleWorkspace()

for ind in range(0,7):
if val>0:
else:
print('')

# Create a data workspace
ws = CreateSampleWorkspace()

# Check masking of first 7 detectors
for ind in range(0,7):
det = ws.getDetector(ind)


Output:

Masked spectrum,   value= 0.0