Jump to: Description · Examples · PARAMETERS · Notes · Changes in CIAO · Bugs · See Also

AHELP for CIAO 4.18 Sherpa

plot

Context: plotting

Synopsis

Create one or more plot types.

Syntax

plot(*args, **kwargs)

No return value.

Description

The plot function creates one or more plots, depending on the arguments it is sent: a plot type, followed by optional identifiers, and this can be repeated. If no data set identifier is given for a plot type, the default identifier - as returned by `get_default_id` - is used. Multiple identifiers can be set with the ids argument and they will be applied to all the plots.

Examples

Example 1

Plot the data for the default data set. This is the same as `plot_data` .

>>> plot("data")

Example 2

Plot the data for data set 2.

>>> plot("data", 2)

Example 3

Plot the data and ARF for the default data set, in two seaparate plots.

>>> plot("data", "arf")

Example 4

Plot the fit (data and model) for data sets 1 and 2, in two separate plots.

>>> plot("fit", 1, "fit", 2)

Example 5

Plot the fit (data and model) for data sets "fit" and "jet", in two separate plots.

>>> plot("fit", "nucleus", "fit", "jet")

Example 6

A single plot is displayed with the fit plot for dataset "jet" overlain on that for dataset "nucleus":

>>> plot("fit", ids=["nucleus", "jet"])

Example 7

Draw the data and model plots both with a log-scale for the y axis:

>>> plot("data", "model", ylog=True)

Example 8

Plot the background data components "up" and "down" for dataset 1:

>>> plot("bkg", 1, "up", "bkg", 1, "down")

Example 9

Draw both data and model for the default dataset in black, but with partial opacity:

>>> plot("data", "model", color="black", alpha=0.5)

Example 10

Draw the two plots in black but with different opacities:

>>> plot("data", "model", color="black", alpha=[1, 0.5])

Example 11

Label each plot (the output depends on the backend and the plot options):

>>> plot("data", "model", label=["data", "model"])

Example 12

Draw the two plots with different y-axis scalings:

>>> plot("data", 2, "model", 2, ylog=[False, True])

Example 13

Change the layout to a single row of plots:

>>> plot("data", "data", 2, rows=1)

Example 14

Use a two-column by three-row display (although in this case only one of the rows or cols arguments needed to be given):

>>> plot("data", "data", 2, "model", "model", 2,
...      "resid", "resid", 2, rows=3, cols=2)

Example 15

Create a display for three plots, vertically aligned, but only display plots in the first two:

>>> plot("data", "model", cols=1, rows=3)

Example 16

Draw the data and residuals for the default dataset and then overplot those from dataset 2:

>>> plot("data", "resid", color="black")
>>> plot("data", 2, "resid", 2, overplot=True, color="black", alpha=0.5)

Example 17

An alternative way to plot multiple datasets is to use the ids argument to define the datasets to use for each plot type:

>>> plot("data", "resid", ids=[1, 2], color="black", alpha=[1, 0.5])

Example 18

Draw the data and residual plots for datasets 1 and 2 with per-plot options. Here, all data will be shown slight transparent (the same value of alpha=0.5 is applied to both datasets), but with different line styles. The first dataset will be shown with a dashed line and the second with a dash-dotted line as specified in the list of linestyle values. The second plot with the residuals will be in orange for both datasets, since opts2 only contains a single value and not a list of parameters.

>>> opts1 = {"linestyle": ["--", "-."], "alpha": 0.5}
>>> opts2 = {"color": "orange"}
>>> plot("data", opts1, "resid", opts2, ids=[1, 2], cols=1)

Example 19

Repeat the plot by specifying the identifiers for each plot, rather than with the ids argument:

>>> plot("data", [1, 2], opts1, "resid", [1, 2], opts2, cols=1)

PARAMETERS

The parameters for this function are:

Parameter	Definition
args	The plot names and identifiers.
rows	The number of rows and columns (if set).
cols	The number of rows and columns (if set).
ids	The identifier, or identifiers, to apply to each plot. If left as None then the value should be given after each plot type.
kwargs	The plot arguments applied to each plot.

Notes

The supported plot types depend on the data set type, and include the following list. There are also individual functions, with plot_ prepended to the plot type, such as `plot_data` . There are also several multiple-plot commands, such as `plot_fit_ratio` , `plot_fit_resid` , and `plot_fit_delchi` .

Item	Definition
arf	The ARF for the data set (only for `DataPHA` data sets).
bkg	The background.
bkg_chisqr	The chi-squared statistic calculated for each bin when fitting the background.
bkg_delchi	The residuals for each bin, calculated as (data-model) divided by the error, for the background.
bkg_fit	The data (as points) and the convolved model (as a line), for the background data set.
bkg_model	The convolved background model.
bkg_ratio	The residuals for each bin, calculated as data/model, for the background data set.
bkg_resid	The residuals for each bin, calculated as (data-model), for the background data set.
bkg_source	The un-convolved background model.
chisqr	The chi-squared statistic calculated for each bin.
data	The data (which may be background subtracted).
delchi	The residuals for each bin, calculated as (data-model) divided by the error.
fit	The data (as points) and the convolved model (as a line).
kernel	The PSF kernel associated with the data set.
model	The convolved model.
model_component	Part of the full model expression (convolved).
model_components	Parts of the full model expression (convolved).
order	Plot the model for a selected response
psf	The unfiltered PSF kernel associated with the data set.
ratio	The residuals for each bin, calculated as data/model.
resid	The residuals for each bin, calculated as (data-model).
source	The un-convolved model.
source_component	Part of the full model expression (un-convolved).
source_components	Parts of the full model expression (un-convolved).

The plots can be specialized for a particular data type, such as the `set_analysis` command controlling the units used for PHA data sets.

Given a plot name, such as "data", the remaining arguments up to the next plot name match those from the corresponding plot_xxx call (in this case plot_data), ignoring the replot, overplot, and clearwindow arguments. So the call

>>> plot("data", "bkg", 1, "up", ylog=True)

can be thought of as combining the plots created by calling plot_data(ylog=True) and plot_bkg(1, "up", ylog=True).

The plot capabilities depend on what plotting backend, if any, is installed. If there is none available, a warning message will be displayed when `sherpa.ui` or `sherpa.astro.ui` is imported, and the `plot` set of commands will not create any plots. The choice of back end is made by changing the options.plot_pkg setting in the Sherpa configuration file.

The keyword arguments are sent to each plot (so care must be taken to ensure they are valid for all plots).

Changes in CIAO

Changed in CIAO 4.18

Multiple data sets can be displayed by using a list of identifiers for supported plots, or via the ids parameter, and per-plot options can now be set with a dictionary.

Changed in CIAO 4.17

The keyword arguments can now be set per plot by using a sequence of values. The layout can be changed with the rows and cols arguments and the automatic calculation no longer forces two rows. Handling of the overplot flag has been improved.

Changed in CIAO 4.15

A number of labels, such as "bkgfit", are marked as deprecated and using them will cause a warning message to be displayed, indicating the new label to use.

Changed in CIAO 4.13

Keyword arguments, such as alpha and ylog, can be sent to each plot.

Bugs

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