Ahelp: ignore - CIAO 3.4

Jump to: Description Examples Bugs See Also

AHELP for CIAO 3.4

ignore

Context: sherpa

Synopsis

Specifies a data portion to be excluded, for 1- or 2-D data.

Syntax

sherpa> IGNORE [{SOURCE | BACK}] [<dataset range> | ALLSETS] [ID] <arg>

where <dataset range> = #, or more generally #:#,#:#,..., such that #
specifies a dataset number, and #:# represents an inclusive range of
datasets; one may specify multiple inclusive ranges by separating them
with commas. The default dataset is dataset 1.

The modifiers SOURCE and BACK may be used to specify that the filter is
to be applied to either the source or background data only. If neither
is specified, then the filter is applied to both the source and
background datasets. Note that in CIAO 3.1 when omitting the modifiers
the definition of INSTRUMENT BACK is required for filtering PHA data in
energy/wave if either background file or background models have been
defined.

The ID modifier is used only for the command IGNORE BACK (see below),
and even then if and only if the Sherpa state object variable multiback
is set to 1, i.e., if more than one background dataset is to be
associated with a single source dataset. The ID modifier may be any
unreserved string (e.g., A, foo, etc.), i.e., a string that is not a
parsable command.

Description

<arg> is either:

IGNORE Command Arguments

Argument	To exclude:
ALL	The entire dataset.
BAD	All PHA channels with quality flags $>$ 0 (1-D only).
FILTER <filterExpr>	Bins with x-values satisfying <filterExpr>.
{BINS \| CHANNELS} <filterExpr>	Bins whose sequential numbers satisfy <filterExpr>.
ENERGY <filterExpr>	Bins with x-values in energy space satisfying <filterExpr> (1-D only).
WAVE <filterExpr>	Bins with x-values in wavelength space satisfying <filterExpr> (1-D only).
PLOT	A range selected interactively from an open plot (1-D only).
IMAGE	A region selected interactively from an open image (2-D only).
{IMAGE \| LOGICAL} <filterExpr>	Pixels with logical coordinates satisfying <filterExpr> (2-D only).
PHYSICAL <filterExpr>	Pixels with physical coordinates satisfying <filterExpr> (2-D only).
{WCS \| WORLD} <filterExpr>	Pixels with world coordinates satisfying <filterExpr> (2-D only).

The typical <filterExpr> for 1-D data is the range filter:

Specification of Range Filters for 1-D Data

This Filter Expression:	Means:
#:#	Exclude all data from the first value to the second value, inclusive.
#:	Exclude all data above the given value, inclusive.
:#	Exclude all data below the given value, inclusive.
#	Exclude the data point corresponding to the given value.

For 2-D data, <filterExpr> is a quote-delimited region specification. See "ahelp dmregions" for more information on allowed region specifications.

For more information on filter expressions, see the Sherpa Filtering Chapter for the full <filterExpr> definition, as well as information regarding other filtering methods.

The difference between the arguments FILTER and {BINS | CHANNELS} may be illustrated with the following simplistic ASCII dataset:

The command IGNORE FILTER 22.65:22.85 will cause the middle two bins to be filtered out. This is equivalent to IGNORE BINS 2:3, i.e., ignore the 2nd and 3rd bins. For PHA datasets, IGNORE FILTER and IGNORE BINS will lead to the same result, since the x-values of the PHA channels are sequential integers: 1, 2, 3...

To use the commands IGNORE ENERGY or IGNORE WAVE, a PHA dataset must have been read in, and an INSTRUMENT model stack defined. Note that regardless of the current ANALYSIS setting, one may filter using either IGNORE ENERGY or IGNORE WAVE. See the examples below.

To specify regions to ignore within an image:

Display the image and mark the filter region(s) (see the IMAGE command). NOTE: only include regions are allowed for filtering (as opposed to exclude regions). Instead of using IGNORE IMAGE with an exclude region, use NOTICE IMAGE with an include region instead. Verify results using IMAGE FILTER.
Issue the command IGNORE [<dataset range> | ALLSETS] IMAGE. This will tell Sherpa to exclude data within the marked region(s).

To specify regions to ignore within a plot:

Plot the data using the LPLOT command).
Issue the command IGNORE [<dataset range> | ALLSETS] PLOT.
Place the cursor on the plot, at the desired minimum x-axis value for the filter, and click once with the left mouse button (or hit the e key).
Place the cursor at the desired maximum x-axis value, and click again with the left mouse button (or hit the e key). Sherpa will then exclude data within the marked region(s).

Ranges/regions to be ignored may be alternatively set using the Sherpa/S-Lang module functions set_ignore, set_ignore_bad, and set_ignore2d, et al.

Example 1

Exclude all data values:

sherpa> DATA example.dat
sherpa> IGNORE ALL

The last command tells Sherpa to ignore all data in dataset 1.

Example 2

Exclude a particular data range from the source, background, or both:

sherpa> DATA data/data.dat
sherpa> BACK data/data_bckg.dat
sherpa> IGNORE SOURCE FILTER 5:10
sherpa> LPLOT 2 DATA BACK

After the input of source and background data, the command IGNORE SOURCE FILTER 5:10 tells Sherpa to exclude those bins in the source dataset whose x-axis values are equal to 5 through 10, inclusive. See the Sherpa Filtering Chapter for further examples of filter expressions and usage of the IGNORE command. With the final command, a plot of both the source and background data illustrates that the filter was applied to the source data only; the background data remains unfiltered.

sherpa> NOTICE ALL
sherpa> IGNORE BACK FILTER 5:10
sherpa> LPLOT 2 DATA BACK
sherpa> LPLOT BFILTER

The NOTICE ALL command eliminates any filters applied to the source and background datasets. The command IGNORE BACK FILTER 5:10 tells Sherpa to exclude those bins in the background dataset whose x-axis values are equal to 5 through 10, inclusive. With the first LPLOT command, a plot of both the source and background data illustrates that the filter was applied to the background data only; the source data remains unfiltered. The final command plots the filter status of each background data point.

sherpa> NOTICE ALL
sherpa> IGNORE FILTER 5:10
sherpa> LPLOT 2 DATA BACK
sherpa> LPLOT FILTER

The NOTICE ALL command eliminates any filters applied to the source and background datasets. The command IGNORE FILTER 5:10 tells Sherpa to exclude those bins in both the source and background datasets whose x-axis values are equal to 5 through 10, inclusive. With the first LPLOT command, a plot of both the source and background data illustrates that the filter was applied to both datasets. The final command plots the filter status of each source data point.

Example 3

Exclude a 2-D region, specified from an image display:

sherpa> READ DATA example_img.fits
sherpa> IMAGE DATA
sherpa> NOTICE ALL
<mark include region(s)>
sherpa> IGNORE IMAGE
sherpa> IMAGE FILTER

In this example, 2-D image data is first displayed. Then the data filter is set to include the entire image, with the command NOTICE ALL. (This command is not needed in this particular example but is shown for completeness.) Next, the user chooses regions, by placing include markers on the displayed image. The command IGNORE IMAGE sets the data filter to exclude data within the marked regions. The command IMAGE FILTER displays the resulting filter.

Example 4

Exclude a 1-D data range, specified from a plot display:

sherpa> READ DATA example.dat
sherpa> LPLOT DATA
sherpa> NOTICE ALL
sherpa> IGNORE PLOT
<left-mouse-click once at the desired minimum x-axis value>
<and then left-mouse-click again at the desired maximum x-axis value>
sherpa> LPLOT FILTER
sherpa> LPLOT DATA

In this example, 1-D data is first displayed. Then the data filter is set to include the entire dataset, with the command NOTICE ALL. (This command is not needed in this particular example but is shown for completeness.) The command IGNORE PLOT readies the cursor for selecting the desired filter region, and the user should then left-mouse-click first at the desired minimum x-axis location and then again at the maximum x-axis location. After the second left-mouse-click, the Sherpa command prompt is returned. The command LPLOT FILTER will then plot the data region that you have marked for exclusion. Finally, the dataset is plotted again, with the command LPLOT DATA, showing that the selected regions have been properly excluded.

Example 5

Exclude a 1-D data range, specified from a plot display, for dataset number 2:

sherpa> READ DATA 1 example1.dat
sherpa> READ DATA 2 example2.dat
sherpa> LPLOT DATA 2
sherpa> NOTICE 2 ALL
sherpa> IGNORE 2 PLOT
<left-mouse-click once at the desired minimum x-axis value>
<and then left-mouse-click again at the desired maximum x-axis value>
sherpa> LPLOT FILTER 2
sherpa> LPLOT DATA 2
sherpa>
sherpa> NOTICE ALL
sherpa> IGNORE PLOT
<left-mouse-click once at the desired minimum x-axis value>
<and then left-mouse-click again at the desired maximum x-axis value>
sherpa> LPLOT FILTER
sherpa> LPLOT DATA

In this example, two 1-D datasets are input, and dataset number 2 is first displayed. Then, the data filter is set to include all of dataset number 2, with the command NOTICE 2 ALL. (This command is not needed in this particular example but is shown for completeness.) The command IGNORE 2 PLOT readies the cursor for selecting the desired filter region for dataset number 2, and the user should then left-mouse-click first at the desired minimum x-axis location and then again at the maximum x-axis location. After the second left-mouse-click, the Sherpa command prompt is returned. The command LPLOT FILTER 2 will then plot the data region that you have marked for exclusion from dataset number 2. Finally, dataset number 2 is plotted again, with the command LPLOT DATA 2, showing that the selected regions have been properly excluded.

Next, the user sets the data filter to include all of dataset number 1, with the command NOTICE ALL. (This command is not needed in this particular example but is shown for completeness.) The command IGNORE PLOT readies the cursor for selecting the desired filter region for dataset number 1, and the user should then left-mouse-click first at the desired minimum x-axis location and then at the maximum x-axis location (from the plot that's currently displayed of dataset number 2). The command LPLOT FILTER will then plot the data region that you have marked for exclusion from dataset number 1. Finally, dataset number 1 is plotted again, with the command LPLOT ALL, showing that the selected regions have been properly excluded. Note that dataset number 1 was interactively filtered, from a display of dataset number 2.

Example 6

Exclude particular data values and ranges:

sherpa> DATA 3 example.dat
sherpa> NOTICE 3 ALL
sherpa> IGNORE 3 FILTER 4, 8:, 1:3

The first command, NOTICE 3 ALL, sets all of dataset number 3 to be included, and so clears any previous filters. (This command is not needed in this particular example but is shown for completeness.) The second command uses a filter expression to exclude those x-axis data values that are equal to 4, greater-than or equal to 8, or equal to 1 through 3, inclusive. See the Sherpa Filtering Chapter for further examples of filter expressions and usage of the IGNORE command.

Example 7

Exclude PHA channels with quality flags different than 0:

sherpa> DATA data/example.pha
sherpa> IGNORE BAD

Example 8

Filter PHA data by energy, or wavelength:

sherpa> ERASE ALL
sherpa> DATA data/example2.pha
The inferred file type is PHA.  If this is not what you want, please
specify the type explicitly in the data command.
WARNING: using systematic errors specified in the PHA file.
RMF is being input from:
<directory_path>/example2.rmf
ARF is being input from:
<directory_path>/example2.arf
Background data are being input from:
<directory_path>/example2_bkg.pha
sherpa> ANALYSIS ENERGY
sherpa> NOTICE ALL
sherpa> IGNORE ENERGY 5:10
sherpa> LPLOT DATA
sherpa> NOTICE ALL
sherpa> IGNORE WAVE 0:20
sherpa> ANALYSIS WAVE
sherpa> LPLOT DATA

In this example, the dataset is filtered using IGNORE WAVE even though the ANALYSIS setting is ENERGY. This is possible because header information in the data file allowed for an instrument model to be automatically defined when the data were initially read.

Example 9

Exclude a 2-D region specified from the command line, in physical coordinates:

sherpa> DATA data/example_img2.fits   
sherpa> IGNORE PHYSICAL "CIRCLE(4010,3928,100)"
sherpa> IMAGE FILTER

To filter in physical coordinates requires no action on the part of the user beyond specifying the PHYSICAL modifier; Sherpa automatically performs the image-to-physical coordinate conversion (if it can). Note that the quote marks are required in CIAO 3.0 when specifying 2-D filter regions. (They are not required when specifying 1-D regions, as seen in the other examples above.) The command IMAGE FILTER displays the resulting filter.

Bugs

See the Sherpa bug pages online for an up-to-date listing of known bugs.