/ sherpa4.17 / ahelp / prof_data.html

Jump to: Description · Examples · RSTEP PARAMETER · Changes in the scripts 4.11.4 (2019) release · CHANGES IN THE DECEMBER 2010 RELEASE · Bugs · See Also

AHELP for CIAO 4.17 Sherpa

prof_data

Context: contrib

Synopsis

Plot a radial or elliptical profile of imaging data.

Syntax

prof_data( [id], [model=None, rstep=None, rmin=None, rmax=None,
rlo=None, rhi=None, xpos=None, ypos=None, ellip=None, theta=None,
group_counts=None, group_snr=None, label=True, recalc=True,
overplot=False, clearwindow=True] )

Description

The prof_data command calculates the radial - or elliptical - profile of the imaging data and plots it. The profile is defined by the existing model compenents, although it is possible to over-ride these values.

Loading the routine

The routine can be loaded into Sherpa by saying:

from sherpa_contrib.profiles import *

What data should be used for the profile?

id - the id of the dataset to use; if not given uses the default sherpa id (see "ahelp get_default_id").

What are the parameters of the radial profile?

The following arguments control the location and ellipticity of the radial profile. For simple cases - where there is only one model component with xpos, ypos, ellip, and theta parameters - then the routine will be able to determine these values automatically. The following options can be used for more complex situations, for instance if you have multiple sources or you want to force circular annuli when the model ellipticity and position angle has been fit.

model - specifies the model component which shold be used to get the xpos, ypos, ellip, and theta values for the profile. If not given then the source model expression is searched to find a component with these parameters; this argument is therefore only needed when there are multiple components with these parameters in a source expression, or you want to use values from a separate model component. The possible values for the argument are the name (string), or the actual component object.
xpos - use this value as the center of the profile along the X axis. If given this overrides the xpos value derived from the model argument. The possible values are a numeric value, the name of a parameter (string), or a parameter object.
ypos - use this value as the center of the profile along the Y axis. If given this overrides the ypos value derived from the model argument. The possible values are a numeric value, the name of a parameter (string), or a parameter object.
ellip - use this value as the ellipticity of the profile. If given this overrides the ellip value derived from the model argument. The possible values are a numeric value, the name of a parameter (string), or a parameter object.
theta - use this value as the theta value for the profile. If given this overrides the theta value derived from the model argument. The possible values are a numeric value, the name of a parameter (string), or a parameter object. This value is only used if the ellipticity is not 0.

The ellipticity and theta values are defined as they are for Sherpa 2D models (e.g. see "ahelp beta2d").

As an example,

sherpa> prof_data(model=clus)

would use the xpos, ypos, ellip, and theta parameters from the clus component for determining the profile, whereas

sherpa> prof_data(model=clus, ellip=0)

would use a circular profile, centered on clus.xpos and clus.ypos (i.e. the clus.ellip and clus.theta parameters would be ignored). Further examples are included in the Examples section below.

What bins should be used for the profile?

The following arguments can be used to determine what radial bins should be used. There are three groups of options:

rlo and rhi are used when you want to bins that are not regularly spaced;
rstep, rmin, and rmax allow you to use a fixed bin size and specify the range (the minimum and maximum values default to the full dataset if not given);
once the data has been binned, it can be re-grouped to ensure either a fixed signal-to-noise ratio or minimum number of counts per output bin (by setting the group_snr or group_counts options).

The following list is organized by priority, in that if rlo is given then it will be used even if rstep is also given. For many cases using just the rstep or either of the group_counts or group_snr options will be sufficient.

rlo - If given, this array determines the left edge of each bin. If rhi is not given then the bins are assumed to be contiguous and the value of the last bin is used as the maximum radius. So rlo=[1,2,4,8,20] will use bins with radii 1-2, 204, 4-8, and 8-20 if rhi is not given.
rhi - If given, this array determines the right edge of the bins. It is only used if rlo is given. So rlo=[1,3,5,9] and rhi=[3,5,7,10] will use bins with radii 1-3, 3-5, 5-7, and 9-10.
rstep - When rlo is not given, the bin width is given by rstep. The default value (which is used when rstep and rlo are not given) is the pixel size of the data. As discussed below rstep can be given as an array to allow variable bin sizes.
rmin - The minimum radius to use; only used when rlo is not given. If not specified defaults to the minimum value of the data (which may not be 0 if the profile center is not within the data or the pixels around the center have been excluded).
rmax - The maximum radius to use; only used when rlo is not given. If not specified defaults to the maximum value of the data. The rmax value is only guaranteed to lie within the bounds of the last bin, depending on the rstep value (and that either group_counts or group_snr is not given).
group_counts - if given, then the bins are grouped so that each bin contains at least group_counts counts in them (before normalisation by the area of the bin). This setting overrides the group_snr value.
group_snr - if given, then the bins are grouped so that the signal-to-noise value for each bin is at least group_snr. It is not used if group_counts is also given.

The units of rlo, rhi, rstep, rmin, and rmax are those of the coordinate system for the dataset (see "ahelp get_coord"). A description of the values supported by the rstep parameter is given below, after the examples, in the "RSTEP PARAMETER" section, which is also accessibla via

unix% ahelp -b ADESC -t "RSTEP PARAMETER" prof_data

When either group_counts or group_snr is used then the last bin displayed is guaranteed to pass the grouping constraint, but it may well be less than the maximum radius given by either rmax or rlo/rhi. The grouping is applied after the initial binning is made; this means that the original bins are calculated using either the rlo/hi or rstep values, then these bins are grouped. This means that using

rstep=10, group_snr=10

may produce different results than

rstep=1, group_snr=10

Two simple examples are:

sherpa> prof_data(rstep=10)

which will use a width of 10 for the bins, and span the full radial range of the data, and

sherpa> prof_data(rstep=5, rmax=100, group_counts=20)

which uses a bin width of 5 out to a radial distance of 100, and then re-bins these values to ensure at least 20 counts per bin. One reason for specifying rmax is that it avoids un-nescessary computation if the range of interest of the profile is significantly smaller than that covered by the data.

How to control the appearance and behavior of the plot

The following options control either the appearance or behavior of the plot.

label - should the position and - if elliptical, the ellipticity and position angle - used to calculate the profile be added as labels to the plot? A value of True (default) means add the labels, and False means the labels should not be added.
recalc - should the cached arrays be used in the plot? A value of True (default) means do the calculation, and False means redisplay the existing values.
overplot - should the new plot be overlaid in the plotting window? A value of False (default) means clear the window, and True means add the new data to any existing plots.
clearwindow - should the plot area be cleared before creating the plot? This is only used if overplot is False.

If the recalc argument is set to True then the plot will use the previously-calculated values to create the plot. This speeds up the routine, but it does mean that any changes you have made to the plot - be it changing the value of one of the routine's arguments such as group_snr and rstep, or to the model itself such as changing the parameters of a model component - will not be reflected in the plot output.

Errors

Errors are calculated using the Gehrel's approximation:

error = 1 + sqrt(N+0.75)

where N is the number of counts in a bin. The signal to noise ratio of a radial bin - used when group_snr is given - is therefore calculated as

N / (1 + sqrt(N+0.75))

(there is no support for including a background level).

Changing the plot defaults

The get_data_prof_prefs() returns the current plot preferences used by prof_data(). Changing these settings will therefore change the appearance of any new plots created by prof_data(). For example

sherpa> get_data_prof_prefs()["xlog"] = True

will cause any new plots to use logarithmic scaling for the X axis. A full list of the preferences can be found by saying

unix% ahelp get_data_prof_prefs

Examples

Example 1

sherpa> load_image("evt2.fits[sky=circle(4203,4304,50)][bin sky=2]")
sherpa> set_coord("physical")
sherpa> set_source(beta2d.src + const2d.bgnd)
sherpa> prof_data()

Load in an image, using the CIAO data model to filter and bin an event file, set the coordinate system to physical (so each image pixel has a width and height of 2 units due to the use of 'bin sky=2'), set a source model consisting of a beta2d component (src) and a constant (bgnd). The use the prof_data call creates a plot a profile of the data.

Since no arguments were given to prof_data, the profile covers the full data range, is in units of the physical pixel size, and uses a bin size of 2 (since this is the pixel size). The center, ellipticity, and position angle (theta) of the profile are taken from the src component, since the bgnd component does not contain xpos, ypos, ellip, or theta parameters. Labels indicating the values of these parameters are added to the top-right of the plot.

As the source model has not yet been fit to the data the profile is probably not going to provide a useful view of the data.

Example 2

sherpa> prefs = get_data_prof_prefs()
sherpa> prefs["xlog"] = True
sherpa> prefs["ylog"] = True
sherpa> prof_data()

The preferences are set so that both the x and y axes should be drawn using log scaling. Setting the get_data_prof_prefs values only affects new plots (i.e. those made after the setting was changed).

Example 3

sherpa> prof_data(group_snr=15)

The data is plotted after the bins have been grouped so that each bin has a signal to noise ratio of 15 or more.

Example 4

sherpa> prof_data(rmin=10, rmax=100, rstep=5)

Calculate the profile in radial bins with low/high limits of 10-15, 15-20, 20-25, ..., 90-95, 95-100. If the group_counts or group_snr option was also given - e.g.

sherpa> prof_data(rmin=10, rmax=100, rstep=5, group_counts=100)

then the grouping would be applied to these bins.

Example 5

sherpa> prof_data(rlo=[0,10,20,40,60,100,200])

Calculate the profile in radial bins with low/high limits of 0-10, 10-20, 20-40, 40-60, 60-100, 100-200.

Example 6

sherpa> prof_data(rstep=[1,10,2,20,5,50,10])

The radii used for the radial bins depends on the radius as shown in the table below:

radius	bin width
0 to 10	1
10 to 20	2
20 to 50	5
above 50	10

The minimum and maximum radii used are taken from the data.

Example 7

sherpa> prof_data("src1")
sherpa> prof_data("src2", overplot=True)

Plots the profile for the dataset called "src1" and then overplots the profile from the dataset "src2".

Example 8

sherpa> load_image("img.fits")
sherpa> set_source(beta2d.clus + gauss2d.qso + const2d.bgnd)
sherpa> fit()
...
sherpa> prof_data(model=qso)
sherpa> thaw(clus.ellip)
sherpa> thaw(clus.theta)
sherpa> fit()
...
sherpa> prof_data(model=clus)

Since the model expression contains two components which have xpos, ypos, ellip, and theta parameters - namely clus and qso - the model argument is used to select the gauss2d (qso) values for the first plot and the beta2d (clus) values for the second plot.

If the clus model has a non-zero ellipticity then the second plot will have used elliptical annuli to calculate the profile. To use circular annuli in this case we can manually override the model's ellipticity parameter by saying:

sherpa> prof_data(model=clus, ellip=0)

RSTEP PARAMETER

The rstep parameter can be given a scalar value - which means to use a single bin width for all bins - or an array of values which allow you to set different bin widths for different radii. The array must contain an odd number of values and is interpreted as

[d1, r1, d2, r2, .., dm, rm, dn]

which means to use the folowing bin widths:

radius	bin width
up to r1	d1
r1 to r2	d2
...	..
r(m-1) to rm	dm
above rm	dn

rstep = [1, 10, 2, 20, 5]

would use a bin size of 1 for radii up to 10, 2 for radii between 10 and 20, and 5 for larger radii. If the bin edges do not match up with the ri values then the switch to the next bin size happens at the first opportunity after ri. This means that

rstep = [0.2, 1, 0.5, 3, 1]

with

rmin = 0.7, rmax=2.4

would use bins 0.7-0.9, 0.9-1.1, 1.1-1.6, 1.6-2.1, and 2.1-2.6.

For more complicated binning patterns it may be easier to use rlo (and possibly rhi) to set the bin edges explicitly.

Changes in the scripts 4.11.4 (2019) release

Plotting can now use matplotlib

The radial-profile plots will now be created in Matplotlib if the plot_pkg setting of your ~/.sherpa.rc file is set to pylab.

CHANGES IN THE DECEMBER 2010 RELEASE

Support for set_full_model

The routines in the module have been updated to support source expressions created using the set_full_model() command introduced in Sherpa 4.2 release 2.

Improved behavior when used with un-filtered data

The code has been updated so as not to require a rmin value when used with data with no spatial filters applied.

Bugs

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