notice2d

Synopsis

Include a spatial region of all data sets.

Syntax

notice2d(val=None)

val - str, optional

Description

Select a spatial region to include in the fit. The filter is applied to all data sets.

Examples

Example 1

Include the data points that lie within a circle centered at 4324.5,3827.5 with a radius of 300:

>>> set_coord("physical")
>>> notice2d("circle(4324.5,3827.5,430)")
dataset 1: Field() -> Circle(4324.5,3827.5,430)
>>> get_filter()
'Circle(4324.5,3827.5,430)'

Example 2

All existing spatial filters are removed:

>>> notice2d()
dataset 1: Circle(4324.5,3827.5,430) -> Field()
>>> get_filter()
''

Example 3

Read in the filter from the file ds9.reg , using either:

>>> set_coord("physical")
>>> notice2d("ds9.reg")
dataset 1: Field() -> Ellipse(3144.52,4518.81,25.2979,19.1119,42.9872)

or, when using CIAO,

>>> set_coord("physical")
>>> notice2d("region(ds9.reg)")
dataset 1: Field() -> Ellipse(3144.52,4518.81,25.2979,19.1119,42.9872)

Example 4

Select those points that lie both within the rotated box and the annulus (i.e. an intersection of the two shapes):

>>> set_coord("logical")
>>> notice2d("rotbox(100,200,50,40,45)*annulus(120,190,20,60)")
dataset 1: Field() -> RotBox(100,200,50,40,45)&Annulus(120,190,20,60)

Example 5

Select those points that lie within the rotated box or the annulus (i.e. a union of the two shapes) combined with the previous filter:

>>> from sherpa.utils.logging import SherpaVerbosity
>>> with SherpaVerbosity("WARN"):
...     notice2d("rotbox(100,200,50,40,45)+annulus(120,190,20,60)")
...

PARAMETERS

The parameter for this function is:

Parameter	Definition
val	A region specification as a string or the name of a file containing a region filter. The coordinates system of the filter is taken from the coordinate setting of the data sets ( `set_coord` ). If none , then all points are included.

Notes

The region syntax support is provided by the CIAO region library, and supports the following shapes (the capitalized parts of the name indicate the minimum length of the name that is supported):

Name	Arguments
RECTangle	(xmin,ymin,xmax,ymax)
BOX	(xcenter,ycenter,width,height)
BOX	(xcenter,ycenter,width,height,angle)
ROTBOX	(xcenter,ycenter,width,height,angle)
CIRcle	(xcenter,ycenter,radius)
ANNULUS	(xcenter,ycenter,iradius,oradius)
ELLipse	(xcenter,ycenter,xradius,yradius,angle)
SECTor	(xcenter,ycenter,minangle,maxangle)
PIE	(xcenter,ycenter,iradius,oradius,minangle,maxangle)
POLYgon	(x1,y1,x2,y2,x3,y3,...)
POInt	(xcenter,ycenter)
REGION	(file)
FIELD	()

Angles are measured in degrees from the X axis, with a positive value indicating a counter-clockwise direction.

Only simple polygons are supported, which means that a polygon can not intersect itself. The last point does not need to equal the first point (i.e. polygons are automatically closed if necessary).

The shapes can be combined using AND (intersection), OR (union), or NOT (negation):

intersection:

shape1()*shape2()
shape1()&shape2()

union:

shape1()+shape2()
shape1()|shape2()
shape1()shape2()

negation:

!shape1()
shape1()-shape2()
shape1()*!shape1()

The precedence uses the same rules as the mathematical operators + and * (with - replaced by *! ), so that:

circle(0,0,10)+rect(10,-10,20,10)-circle(10,0,10)

means that the second circle is only excluded from the rectangle, and not the first circle. To remove it from both shapes requires writing:

circle(0,0,10)-circle(10,0,10)+rect(10,-10,20,10)-circle(10,0,10)

A point is included if the center of the pixel lies within the region. The comparison is done using the selected coordinate system for the image, so a pixel may not have a width and height of 1.

The REGION specifier is only supported when using CIAO. Unfortunately you can not combine region shapes using this syntax. That is region(s1.reg)+region(s2.reg) is not supported.

The report of the change in the filter expression can be controlled with the `SherpaVerbosity` context manager, as shown in the examples below.

Changes in CIAO

Changed in CIAO 4.15

The change in the filter is now reported for each dataset.

Bugs

See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.