Last modified: June 2019

URL: https://cxc.cfa.harvard.edu/sherpa/ahelp/prof_data.html
AHELP for CIAO 4.16 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?

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.

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:

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.

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.

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

So

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.

See Also

contrib
get_data_prof, get_data_prof_prefs, get_delchi_prof, get_delchi_prof_prefs, get_fit_prof, get_model_prof, get_model_prof_prefs, get_resid_prof, get_resid_prof_prefs, get_source_prof, get_source_prof_prefs, plot_chart_spectrum, plot_marx_spectrum, prof_delchi, prof_fit, prof_fit_delchi, prof_fit_resid, prof_model, prof_resid, prof_source, sherpa_profiles
data
get_arf_plot, get_bkg_chisqr_plot, get_bkg_delchi_plot, get_bkg_fit_plot, get_bkg_model_plot, get_bkg_plot, get_bkg_ratio_plot, get_bkg_resid_plot, get_bkg_source_plot
modeling
normal_sample, t_sample, uniform_sample
plotting
get_cdf_plot, get_energy_flux_hist, get_pdf_plot, get_photon_flux_hist, get_pvalue_plot, get_pvalue_results, get_split_plot, plot, plot_arf, plot_bkg, plot_bkg_chisqr, plot_bkg_delchi, plot_bkg_fit, plot_bkg_fit_delchi, plot_bkg_fit_resid, plot_bkg_model, plot_bkg_ratio, plot_bkg_resid, plot_bkg_source, plot_cdf, plot_chisqr, plot_data, plot_delchi, plot_energy_flux, plot_fit, plot_fit_delchi, plot_fit_resid, plot_model, plot_model_component, plot_order, plot_pdf, plot_photon_flux, plot_pvalue, plot_ratio, plot_resid, plot_scatter, plot_source, plot_source_component, plot_trace, set_xlinear, set_xlog, set_ylinear, set_ylog
psfs
plot_kernel
statistics
get_chisqr_plot, get_delchi_plot
visualization
contour_resid