Ahelp: notice - CIAO 3.4

Jump to: Description Examples Bugs See Also

AHELP for CIAO 3.4

notice

Context: sherpa

Synopsis

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

Syntax

sherpa> NOTICE [{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:

NOTICE Command Arguments

Argument	To include:
ALL	The entire dataset.
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:
#:#	Include all data from the first value to the second value, inclusive.
#:	Include all data above the given value, inclusive.
:#	Include all data below the given value, inclusive.
#	Include 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 NOTICE FILTER 22.65:22.85 will cause the middle two bins to be included in the filter. This is equivalent to NOTICE BINS 2:3, i.e., notice the 2nd and 3rd bins. For PHA datasets, NOTICE FILTER and NOTICE 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 NOTICE ENERGY or NOTICE 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 NOTICE ENERGY or NOTICE WAVE. See the examples below.

To specify regions to notice 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 NOTICE IMAGE with an exclude region, use IGNORE IMAGE with an include region instead. Verify results using IMAGE FILTER.
Issue the command IGNORE [<dataset range> | ALLSETS] ALL. Note that if this is the first type the NOTICE command below is to be issued for a particular dataset, the user need not issue the command IGNORE ALL.
Issue the command NOTICE [<dataset range> | ALLSETS] IMAGE. This will tell Sherpa to include data within the marked region(s).

To specify regions to notice within a plot:

Plot the data using the LPLOT command).
Issue the command IGNORE [<dataset range> | ALLSETS] ALL. Note that if this is the first type the NOTICE command below is to be issued for a particular dataset, the user need not issue the command IGNORE ALL.
Issue the command COMMAND [<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 include data within the marked region(s).

Ranges/regions to be notices may be alternatively set using the Sherpa/S-Lang module functions set_notice and set_notice2d, et al.

Example 1

Include all data values:

sherpa> DATA example.dat
sherpa> NOTICE ALL

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

Example 2

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

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

After the input of source and background data, the command NOTICE SOURCE FILTER 5:10 tells Sherpa to include those bins in the source dataset whose x-axis values are equal to 5 through 10, inclusive. Note that the preceding IGNORE SOURCE ALL command is not strictly necessary, but is included here for completeness. 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 ALL
sherpa> NOTICE 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 NOTICE BACK FILTER 5:10 tells Sherpa to include those bins in the background dataset whose x-axis values are equal to 5 through 10, inclusive. Note that the preceding IGNORE BACK ALL command is not strictly necessary, but is included here for completeness. 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> IGNORE ALL
sherpa> NOTICE FILTER 5:10
sherpa> LPLOT 2 DATA BACK
sherpa> LPLOT FILTER

The NOTICE FILTER 5:10 command tells Sherpa to exclude those bins in both the source and background datasets whose x-axis values are equal to 5 through 10, inclusive. Note that the preceding IGNORE ALL command is not strictly necessary, but is included here for completeness. 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

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

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

In this example, 2-D image data is first displayed. Then the data filter is set to exclude 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 NOTICE IMAGE sets the data filter to exclude data within the marked regions. The command IMAGE FILTER displays the resulting filter.

Example 4

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

sherpa> READ DATA example.dat
sherpa> LPLOT DATA
sherpa> IGNORE ALL
sherpa> NOTICE 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 exclude the entire dataset, with the command IGNORE ALL. (This command is not needed in this particular example but is shown for completeness.) The command NOTICE 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 inclusion. Finally, the dataset is plotted again, with the command LPLOT DATA, showing that the selected regions have been properly included.

Example 5

Include 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> IGNORE 2 ALL
sherpa> NOTICE 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> IGNORE ALL
sherpa> NOTICE 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 exclude all of dataset number 2, with the command IGNORE 2 ALL. (This command is not needed in this particular example but is shown for completeness.) The command NOTICE 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 inclusion 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 included.

Next, the user sets the data filter to exclude all of dataset number 1, with the command IGNORE ALL. (This command is not needed in this particular example but is shown for completeness.) The command NOTICE 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 inclusion from dataset number 1. Finally, dataset number 1 is plotted again, with the command LPLOT DATA, showing that the selected regions have been properly included. Note that dataset number 1 was interactively filtered, from a display of dataset number 2.

Example 6

Include particular data values and ranges:

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

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

Example 7

Filter PHA data by energy, or wavelength:

sherpa> ERASE ALL
sherpa> DATA example.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>/example.rmf
ARF is being input from:
<directory_path>/example.arf
Background data are being input from:
<directory_path>/example_bkg.pha
sherpa> ANALYSIS ENERGY
sherpa> IGNORE ALL
sherpa> NOTICE ENERGY 5:10
sherpa> LPLOT DATA
sherpa> IGNORE ALL
sherpa> NOTICE WAVE 0:20
sherpa> ANALYSIS WAVE
sherpa> LPLOT DATA

In this example, the dataset is filtered using NOTICE 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 8

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

sherpa> DATA data/example_img2.fits
sherpa> NOTICE 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.