next up previous
Next: 3. Sherpa Filtering Up: Sherpa Reference Manual Previous: 1. Sherpa Commands

Subsections


2. Sherpa Display


2.1 Introduction

In this Chapter, the commands that are available from within Sherpa for displaying 1- and 2-D data are described.


2.2 1-D Plotting

1-D plotting within Sherpa may be performed using the LPLOT command:

sherpa> LPLOT $ <$arg$ >$ $ [$#$ ]$ $ [${UP | DOWN}$ ]$

where # may specify the dataset (default dataset number is 1).

$ <$arg$ >$ may be:

Argument: To display:
BACK The background data values.
BACKERRORS The background error values.
{BACKFIT | BFIT} The background data and the best-fit background model simultaneously.
{BACKGROUND | BG} The (unconvolved) background model amplitudes.
BCHISQU The contributions to the $ \chi ^2$ statistic in the background fit.
BDELCHI The residuals of the background fit ( $ (data - model)/error$).
BFILTER The filter status of each background data point.
{BFIT | BACKFIT} The background data and the best-fit background model simultaneously.
{BG | BACKGROUND} The (unconvolved) background model amplitudes.
BRATIO The background data/model ratio value for each data point.
BRESIDUALS The residuals of the background fit ( $ data - model$).
BSTATISTIC The contributions to the currently defined background fit statistic.
CHI SQU The contributions to the $ \chi ^2$ statistic.
DATA The source data.
DELCHI The residuals of the fit ( $ (data - model)/error$).
ERRORS The source data error values.
FILTER The filter status of each data point.
FIT The source data and the best-fit source model simultaneously.
$ <$modelname$ >$ The specified model component amplitudes (unconvolved).
MODEL The (convolved) source model amplitudes.
RATIO The data/model ratio value for each data point.
RESIDUALS The residuals of the fit ( $ data - model$).
SOURCE The (unconvolved) source model amplitudes.
STATISTIC The contributions to the currently defined fit statistic.
USERSTAT The contributions to the user-defined fit statistic.
WEIGHTS The weight assignments for each data point.

The modifiers UP and DOWN may be used with BACK, BACKERRORS, BACKFIT, and BACKGROUND. They relate specifically to the analysis of Chandra grating data and thus may be ignored in most applications.

Note: If there is no open plotting window when an LPLOT command is given, one will be launched automatically. Plotting display windows may be closed simply by closing the window with a mouse click.

In addition, 1-D plotting within Sherpa , of instrument responses stored in a Fits Embedded Function (FEF) file that is read in via FEFFILE (See Chapter 1, Section 1.33), may be plotted using FEFPLOT:

sherpa> FEFPLOT {$ <$photon_energy$ >$ | $ <$photon_wavelength$ >$}

where {$ <$photon_energy$ >$ | $ <$photon_wavelength$ >$} must be in the same units that are used for photon energies in the FEF file (conventionally, keV or Å).

Examples:

  1. Display 1-D data: 
    sherpa> READ DATA 2 example.dat
sherpa> LPLOT DATA 2
    The last command plots dataset number 2. Dataset number 2 must be a 1-D dataset.

  2. Display a fit to 1-D data: 
    sherpa> PARAMPROMPT OFF
sherpa> SOURCE 2 = POLY[modela]
sherpa> THAW modela.1 modela.2 modela.3
sherpa> GUESS SOURCE 2
sherpa> FIT 2
sherpa> LPLOT FIT 2
    Following a fit to dataset number 2, the last command plots the fit.

  3. Read in part of a FEF file, and plot the response as a function of counts-space energy, at photon energy 2.4 keV: 
    sherpa> FEFFILE "data/fef_response.fits[function] \
[ccd_id=0,chipx>=1,chipx<=256,chipy>=1,chipy<=32]"
sherpa> FEFPLOT 2.4
    The appearance of the plot may be subsequently altered using ChIPS commands such as: 
    sherpa> LIMITS X 0 3
sherpa> REDRAW

Additional LPLOT command examples may be found throughout this Chapter, and in Chapter 1, Section 1.51.


2.2.1 1-D Plot Controls

There are two types of control commands for 1-D plots available from within Sherpa :

  1. Sherpa 1-D plot control commands. This type of plot control command requires that an LPLOT command be issued, in order for the plot display to be updated. That is, the plot display is not automatically redrawn when a Sherpa plot control command is issued. See Subsection 2.2.2, below.

  2. ChIPS 1-D plot control commands. This type of plot control command requires that a REDRAW command be issued, in order for the plot display to be updated. That is, the plot display is not automatically redrawn when a ChIPS plot control command is issued. See Subsection 2.2.3, below.


2.2.2 Sherpa 1-D Plot Controls

Note that the LPLOT command must be issued, in order to see the results of previously issued SET, PLOTX, and/or PLOTY commands.

Examples:

  1. Plot data and change error bars, x-axis range, and scale: 
    sherpa> DATA data/example.dat 1 2
sherpa> LPLOT DATA
sherpa> SET PLOT NOERRORBARS
sherpa> LPLOT DATA
sherpa> SET PLOT RANGE 1600:1640
sherpa> LPLOT DATA
sherpa> SET PLOT LOG LINEAR
sherpa> LPLOT DATA
    The first LPLOT DATA command produces a plot with default settings. The command SET PLOT NOERRORBARS sets for no error bars to be plotted, and then the LPLOT DATA command causes the plot to be redrawn with this new setting. Then the command SET PLOT RANGE 1600:1640 changes the Axis 0 (x-axis) range; the LPLOT DATA command causes the plot to be redrawn with this new setting. Next, the Axis 0 scale is changed to log scale, and again the plot is redrawn using the LPLOT DATA command.

    Note that the following sequence of commands would also produce the same plot: 

    sherpa> DATA data/example.dat 1 2
sherpa> SET PLOT NOERRORBARS
sherpa> SET PLOT RANGE 1600:1640 
sherpa> SET PLOT LOG LINEAR 
sherpa> LPLOT DATA

    Also note that the same plot may be produced using ChIPS plot control commands; see Section 2.2.3, Example 1.

  2. Restore plot to default errorbars, x-axis range, and scale: 
    sherpa> SET PLOT ERRORBARS
sherpa> SET PLOT AUTORANGE
sherpa> SET PLOT LINEAR LINEAR
sherpa> LPLOT DATA
    Following the above example, this set of commands restores the plot to the original default setting.

    The same plot may be produced using ChIPS plot control commands; see Section 2.2.3, Example 2.

  3. Change the x-axis and y-axis unit types, for the display of dataset number 2: 
    sherpa> READ DATA 2 data/example.pha
sherpa> RSP[instrumentA](data/example.rmf, data/example.arf) 
sherpa> INSTRUMENT 2 = instrumentA
sherpa> SET PLOT NOERRORBARS
sherpa> PLOTX 2 ENERGY
sherpa> LPLOT DATA 2
sherpa> PLOTX 2 CHANNEL
sherpa> LPLOT DATA 2
sherpa> PLOTY 2 COUNTS
sherpa> LPLOT DATA 2
    The PLOTX 2 ENERGY command sets the unit type, for the x-axis of the plot, for dataset number 2, to energy. The next LPLOT command then plots dataset number 2 using this new Axis 0 setting. Note that the PLOTX command cannot be successfully issued without first defining the instrument model to be used (see Chapter 1, Section 1.46). The PLOTY 2 COUNTS command sets the unit type, for the y-axis of the plot, for dataset number 2, to counts. The next LPLOT command then plots dataset number 2 using this new Axis 1 setting.

  4. Plot into multiple windows: 
    sherpa> PLOTX 2 ENERGY
sherpa> PLOTY 2 RATE
sherpa> LPLOT DATA 2
sherpa> LPLOT 2 DATA 1 DATA 2
    The final command creates two drawing areas, and plots dataset number 1 in the first drawing area, and dataset number 2 in the second drawing area. Note that in this example, the command LPLOT 2 DATA 1 DATA 2 could be replaced with the simpler command LPLOT 2 DATA 1:2, or LPLOT 2 DATA ALL.

  5. Have plotted data written to output data files: 
    sherpa> ERASE ALL
sherpa> DATA data/example1a.dat
sherpa> SET PLOT NOERRORBARS
sherpa> LPLOT DATA
sherpa> STORE myplot1.chp
sherpa> SAVE ALL mysession1.shp
sherpa> ls myplot1.chp*
myplot1.chp             
myplot1.chp.fits
sherpa> ls mysession1.shp*
mysession1.shp
sherpa> EXIT
Goodbye.
    The STORE command specifies that a record of the commands used to generate the plot be saved in an ASCII file named myplot1.chp. The STORE command also creates a FITS file that contains the plotted data (e.g. myplot1.chp.fits). The command SAVE ALL mysession1.shp is useful for saving the current state of the Sherpa session; the current session may be restored at a later time by using the mysession1.shp file as a Sherpa script. For example, after exiting Sherpa , one may restore the stored plot using the ChIPS command RESTORE: 
    sherpa> RESTORE myplot1.chp
sherpa> SHOW
    And, one may also resume the saved Sherpa session using the Sherpa command USE: 
    sherpa> USE mysession1.shp
sherpa> SHOW
    Note that when multiple curves have been plotted, the data for each curve is saved in a different extension of the STORE command's output FITS file. For example: 
    sherpa> PARAMPROMPT OFF
Model parameter prompting is off
sherpa> GAUSS[modela]
sherpa> SOURCE 1 = modela
sherpa> FIT
 powll: v1.2
 powll:   initial function value =     7.75333E-28
 powll:     converged to minimum =     3.54037E-28 at iteration =      9
 powll:   final function value    =     3.54037E-28
        modela.fwhm  15.8599     
        modela.pos  1615.64     
        modela.ampl  1.11265e-14     

sherpa> SET PLOT NOERRORBARS
sherpa> LPLOT FIT
sherpa> STORE myplot2.chp
sherpa> ls myplot2.chp*
myplot2.chp         
myplot2.chp.fits
sherpa> PRISM myplot2.chp.fits
    Examination of the FITS file myplot2.chp.fits using Prism should show that the data are saved in the first FITS extension, and the fit data are saved in the second extension. See the ChIPS Reference Manual for further information regarding the ChIPS STORE and RESTORE commands.

Additional SET command examples may be found in Chapter 1, Section 8.80. Additional PLOTX and PLOTY examples may be found in Chapter 1, Sections 1.59 and 1.60, respectively.


2.2.3 ChIPS 1-D Plot Controls

All ChIPS commands are available from within Sherpa . See the ChIPS Reference Manual for complete ChIPS command definitions and further examples.

Note that ChIPS plot control commands require that a REDRAW command be issued, in order for the plot display to be updated.

Examples:

  1. Plot data and change x-axis range and scale: 
    sherpa> DATA data/example.dat 1 2
sherpa> LPLOT DATA
sherpa> ERRS NONE
sherpa> LIMITS X 1600 1640
sherpa> AXIS LOG X
sherpa> REDRAW
    The first LPLOT DATA command produces a plot with default settings. The ChIPS command ERRS NONE sets for no error bars to be plotted. The ChIPS command LIMITS X 1600 1640 changes the Axis 0 (x-axis) range. Next, the Axis 0 scale is changed to log scale. Note that the plot display is not automatically redrawn when ChIPS plot control commands are issued; the ChIPS command REDRAW must be issued.

    The same plot may be produced using Sherpa plot control commands; see Section 2.2.2, Example 1.

  2. Restore plot to default x-axis range and scale: 
    sherpa> ERRS STANDARD
sherpa> AXIS LINEAR X  
sherpa> LIMITS X AUTO AUTO
sherpa> REDRAW
    Following the above example, this set of commands restores the plot to the original default setting.

    The same plot may be produced using Sherpa plot control commands; see Section 2.2.2, Example 2.

  3. Plot two data datasets, each in separate windows; change x-axis range and scale of one plot: 
    sherpa> ERASE ALL
sherpa> READ DATA 1 data/example.dat 1 2
sherpa> READ DATA 2 data/example2.dat 1 2
sherpa> LPLOT 2 DATA 1 DATA 2
sherpa> D 1 LABEL 1.0 15.0 "Drawing Area Number 1"
sherpa> D 2 LABEL 1.0 55.0 "Drawing Area Number 2"
sherpa> D 1 LIMITS X 1600 1640
sherpa> D 1 LOG X
sherpa> REDRAW
    The Sherpa plot control command LPLOT 2 DATA 1 DATA 2 produces two plot windows, each with default settings. Dataset number 1 is plotted in drawing area number 1, and dataset number 2 is plotted in drawing area number 2. The ChIPS plot control command D 1 LIMITS X 1600 1640 changes the Axis 0 (x-axis) range for the plot in the first drawing area. Next, another ChIPS plot control command changes the Axis 0 scale to log scale, for the plot in drawing area number 1.

  4. Utilize various ChIPS plot control commands: 
    sherpa> ERASE ALL
sherpa> DATA data/example.dat 1 2
sherpa> PARAMPROMPT OFF
Model parameter prompting is off
sherpa> POLY[model1]
sherpa> SOURCE = model1
sherpa> THAW model1.c0 model1.c1 model1.c2
sherpa> FIT
sherpa> LPLOT FIT
    With the above commands, an ASCII dataset is input and then fit with a polynomial. The LPLOT FIT command produces a plot of the data and the resulting fit, with default settings. 
    sherpa> C 1 NOLINE
sherpa> C 1 SYMBOL CROSS
sherpa> C 2 SIMPLELINE
sherpa> REDRAW
    This plot possesses two curves: curve 1 is the data curve, and curve 2 is the fit function. In this example, ChIPS plot control commands are issued, to modify each curve of the plot. First, the data curve is changed to points, and then the points are changed to the cross symbol. Lastly, the fit function curve is changed to a line. 
    sherpa> LIMITS Y 0 4.25
sherpa> TICKVALS Y %1.1f
sherpa> REDRAW
    The Axis 1 (y-axis) lower and upper limits are modified, using the ChIPS LIMITS command. Then the ChIPS command TICKVALS is used to set the format for the y-axis tick labels. 
     
sherpa> XLABEL "Arc Minutes"
sherpa> YLABEL "SNR"
sherpa> TITLE "HRC-I"
sherpa> LABEL 5 0.5 "(0.606)+(0.419)X-(0.014)X^2"
sherpa> REDRAW
    Various ChIPS commands are issued to add Axis labels and a title. The last command places a label at the position of (5, 0.5). 
      
sherpa> XLABEL BLUE
sherpa> YLABEL BLUE
sherpa> TITLE BLUE
sherpa> LABEL RED
sherpa> REDRAW
    The label and title color attributes are modified using ChIPS commands.

  5. Save a plot as a PostScript file: 
    sherpa> PRINT POSTFILE example_plot.ps
    This command prints the current plot to a PostScript file named example_plot.ps.

  6. Plot data with the ChIPS CURVE command: 
    sherpa> ERASE ALL
sherpa> CURVE data/example.dat x 1 y 2
sherpa> REDRAW
    Within Sherpa , a dataset may be directly plotted from a file, using the ChIPS command CURVE. The above CURVE command plots the file data/example.dat; the first two columns of this ASCII data file are the x-axis and y-axis data. 
    sherpa> C 1 DEL
sherpa> CURVE data/example.dat x 3 y 4
sherpa> REDRAW
    This CURVE command plots the third and fourth columns as the x and y data. Note that the first curve is deleted before another CURVE command is issued. This deletion is necessary in this example, because each CURVE commands appends a curve to the plot (that is, successive CURVE commands do not overwrite each other, they instead overlay each other).

  7. Plot data with x-axis error bars: 
    sherpa> ERASE ALL
sherpa> CURVE data/example.dat x 1 y 2 XUP 3 XDOWN 4
sherpa> REDRAW
    In order to utilize ChIPS commands for plotting errorbars, the ChIPS CURVE command must be used. The CURVE command given above plots data from the file data/example.dat; the first two columns are the x and y data, while the third and fourth columns are the positive and negative x-axis errorbars, respectively. 
    sherpa> C 1 DEL
sherpa> CURVE data/example.dat x 1 y 2 xerr 3
sherpa> REDRAW
    This CURVE command plots the first two columns as the x and y data, while the third column is read for symmetrical x-axis errorbars. Note that the first curve is deleted before another CURVE command for the same data is issued.

  8. Plot data with y-axis error bars: 
    sherpa> ERASE ALL
sherpa> CURVE data/example.dat x 1 y 2 YUP 5 YDOWN 6
sherpa> REDRAW
    The CURVE command given above plots data from the file data/example.dat; the first two columns are the x and y data, while the fifth and sixth columns are the positive and negative y-axis errorbars, respectively. The plot may be changed to include only the positive y-axis errorbars, only the negative y-axis errorbars, both, or none: 
    sherpa> ERRS y UP
sherpa> REDRAW
sherpa> ERRS y DOWN
sherpa> REDRAW
sherpa> ERRS y BOTH
sherpa> REDRAW
sherpa> ERRS y NONE
sherpa> REDRAW

  9. Plot data with symmetrical y-axis error bars: 
     
sherpa> ERASE ALL
sherpa> CURVE data/example5b.dat x 1 y 2 yerr 5
sherpa> REDRAW
    This command plots the first two columns of data, and uses column five to plot symmetrical y-axis errorbars. The following commands are each equivalent to the above CURVE command: 
    sherpa> CURVE data/example5b.dat x 1 y 2 e 5
sherpa> CURVE data/example5b.dat 1 2 5


2.2.4 Interactive Filtering from 1-D Plots

Filter regions may be specified from a plot, using the following steps:

  1. Plot the data using LPLOT.
  2. Issue the command IGNORE $ [$ $ <$dataset range$ >$ | ALLSETS $ ]$ PLOT or the command NOTICE $ [$ $ <$dataset range$ >$ | ALLSETS $ ]$ PLOT.
  3. Place the cursor on the plot, at the desired minimum x-axis value for the filter, and click once with the left mouse button.
  4. Place the cursor at the desired maximum x-axis value, and click again with the left mouse button.

This will set the data filter to either include (for NOTICE) or exclude (for IGNORE) the marked region of the dataset. Note that the character e may be used as an alternative to clicking the left mouse button.

See Chapter 1, Section 1.44, Examples 1 and 4.


2.2.5 Interactive Assignment of Parameter Values from 1-D Plots

Model parameter values may be assigned from a plot, using the following steps:

One may quit GETX or GETY by typing q, with the the previously assigned parameter value restored. Note, however, that if multiple parameter values are being set, only the one being altered when q is typed has its value restored.

See Chapter 1, Sections 1.39 and 1.40 for examples.


2.2.6 1-D Overplotting

1-D overplotting within Sherpa may be performed using the OPLOT command:

sherpa> OPLOT $ <$curve_arg1$ >$ $ <$curve_arg2$ >$ ...

where the arguments $ <$curve_arg1$ >$ $ <$curve_arg2$ >$ ... should each be replaced with a valid plotting command argument of the form $ <$arg$ >$ $ [$#$ ]$ $ [${UP | DOWN}$ ]$, such that $ <$arg$ >$ is any of the OPLOT arguments listed below, and where # specifies a dataset number (default dataset number is 1).

$ <$arg$ >$ may be:

Argument: To display:
BACK The background data values.
BACKERRORS The background error values.
BFILTER The filter status of each background data point.
BACKGROUND The (unconvolved) background model amplitudes.
BRATIO The background data/model ratio value for each data point.
BRESIDUALS The residuals of the background fit, in units of sigma.
BSTATISTIC The contributions to the currently defined background fit statistic.
CHI SQU The contributions to the $ \chi ^2$ statistic.
DATA The source data.
ERRORS The source data error values.
FILTER The filter status of each data point.
$ <$modelname$ >$ The specified model component amplitudes (unconvolved).
MODEL The (convolved) source model amplitudes.
RATIO The data/model ratio value for each data point.
RESIDUALS The residuals of the fit, in units of sigma.
SOURCE The (unconvolved) source model amplitudes.
STATISTIC The contributions to the currently defined fit statistic.
USERSTAT The contributions to the user-defined fit statistic.
WEIGHTS The weight assignments for each data point.

The modifiers UP and DOWN may be used with BACK, BACKERRORS, BACKFIT, and BACKGROUND; they relate specifically to the analysis of Chandra grating data and thus may be ignored in most applications.

Note: If there is no open plotting window when an OPLOT command is given, one will be launched automatically. Plotting display windows, may be closed simply by closing the window with a mouse click.

Examples:

  1. Display 1-D data: 
    sherpa> DATA data/example1.dat
sherpa> DATA 2 data/example2.dat
sherpa> OPLOT DATA 1 DATA 2
    The OPLOT command causes both dataset number 1 and dataset number 2 to be plotted in the same window.


2.3 2-D Imaging

2-D imaging within Sherpa may be performed using the IMAGE command:

sherpa> IMAGE $ <$arg$ >$ $ [$#$ ]$ $ [${FILTERED | UNFILTERED}$ ]$

where # may specify the dataset (default dataset number is 1). By default, filtered datasets are imaged.

$ <$arg$ >$ may be:

Argument: To display:
BACK The background data values.
BACKERRORS The background error values.
{BACKFIT | BFIT} The background data and the best-fit background model simultaneously.
{BACKGROUND | BG} The (unconvolved) background model amplitudes.
BCHISQU The contributions to the $ \chi ^2$ statistic in the background fit.
BDELCHI The residuals of the background fit ( $ (data - model)/error$).
BFILTER The filter status of each background data point.
{BFIT | BACKFIT} The background data and the best-fit background model simultaneously.
{BG | BACKGROUND} The (unconvolved) background model amplitudes.
BRATIO The background data/model ratio value for each data point.
BRESIDUALS The residuals of the background fit ( $ data - model$).
BSTATISTIC The contributions to the currently defined background fit statistic.
CHI SQU The contributions to the $ \chi ^2$ statistic.
DATA The source data.
DELCHI The residuals of the fit ( $ (data - model)/error$).
ERRORS The data error values.
FILTER The filter status of each data point.
FIT The data, the best-fit model, and the sigma residuals.
$ <$modelname$ >$ The specified model component amplitudes (unconvolved).
MODEL The (convolved) source model amplitudes.
RATIO The data/model ratio value for each data point.
RESIDUALS The residuals of the fit ( $ data - model$).
SOURCE The (unconvolved) source model amplitudes.
STATISTIC The contributions to the currently defined fit statistic.
USERSTAT The contributions to the user-defined fit statistic.
WEIGHTS The weight assignment for each data point.

Note that if there is no open imager when an IMAGE command is given, one will be created automatically. Image display windows may be closed simply by closing the window with a mouse click. Also, the command CLOSE may be used to close an image display window.

Examples:

  1. Display 2-D data: 
    sherpa> READ DATA 2 example_img.fit
sherpa> IMAGE DATA 2
    The last command displays dataset number 2. Dataset number 2 must be a 2-D dataset.

Additional IMAGE command examples may be found in Chapter 1, Section 1.45.


2.3.1 Interactive Filtering from 2-D Images

Filter regions may be specified from an image, using the following steps:

  1. Display the image and mark the filter region(s) (see the IMAGE command, Chapter 1, Section 1.45). Note: use include regions (as opposed to exclude regions) for optimal results. For instance, do not do IGNORE IMAGE using an exclude region; it will lead to an incorrect result in the current version of Sherpa . Use NOTICE IMAGE with an include region instead. Placing exclude region boundaries within include region boundaries will usually work, however. Verify results using IMAGE FILTER.
  2. Issue the command IGNORE $ [$ $ <$dataset range$ >$ | ALLSETS $ ]$ IMAGE or the command NOTICE $ [$ $ <$dataset range$ >$ | ALLSETS $ ]$ IMAGE.

This will set the data filter to either include (for NOTICE) or exclude (for IGNORE) the marked region of the dataset.

Also note: If you re-display an image following filtering, the filtered image data will be displayed if possible. There are some situations when this is not possible, however: currently, arbitrary filters cannot be passed from Sherpa to the imaging display. Instead, only rectangles can be passed. And, the rectangle that's passed is one that's the smallest possible around the noticed data. If this rectangle is not smaller than the dataset, then the entire dataset will be shown.

See Chapter 1, Section 1.44, Example 3; and Chapter 1, Section 1.55, Example 4.


2.4 2-D Plotting

2-D plotting within Sherpa may be performed using the CPLOT and SPLOT commands:

The CPLOT command causes the specified 2-D data to be displayed, with a contour plot, via ChIPS (Chandra Imaging and Plotting System):

sherpa> CPLOT $ <$arg$ >$ $ [$#$ ]$

The SPLOT command causes the specified 2-D data to be displayed, with a surface plot, via ChIPS (Chandra Imaging and Plotting System):

sherpa> SPLOT $ <$arg$ >$ $ [$#$ ]$

where # may specify the dataset (default dataset number is 1).

$ <$arg$ >$ for either CPLOT or SPLOT may be:

Argument: To display:
BACK The background data values.
BACKERRORS The background error values.
{BACKGROUND | BG} The (unconvolved) background model amplitudes.
BCHISQU The contributions to the $ \chi ^2$ statistic in the background fit.
BDELCHI The residuals of the background fit ( $ (data - model)/error$).
BFILTER The filter status of each background data point.
{BG | BACKGROUND} The (unconvolved) background model amplitudes.
BRATIO The background data/model ratio value for each data point.
BRESIDUALS The residuals of the background fit ( $ data - model$).
BSTATISTIC The contributions to the currently defined background fit statistic.
CHI SQU The contributions to the $ \chi ^2$ statistic.
DATA The source data.
DELCHI The residuals of the fit ( $ (data - model)/error$).
ERRORS The source data error values.
FILTER The filter status of each data point.
$ <$modelname$ >$ The specified model component amplitudes (unconvolved).
MODEL The (convolved) source model amplitudes.
RATIO The data/model ratio value for each data point.
RESIDUALS The residuals of the fit ( $ data - model$).
SOURCE The (unconvolved) source model amplitudes.
STATISTIC The contributions to the currently defined fit statistic.
USERSTAT The contributions to the user-defined fit statistic.
WEIGHTS The weight assignments for each data point.

Note that, if there is not a plotting window currently open, any CPLOT or SPLOT command will automatically launch one. Plotting display windows may be closed simply by closing the window with a mouse click.

In addition, like LPLOT, surface and contour plots may be displayed into multiple windows:

sherpa> CPLOT $ [$#$ ]$ $ <$wind1$ >$ $ <$wind2$ >$ ...
sherpa> SPLOT $ [$#$ ]$ $ <$wind1$ >$ $ <$wind2$ >$ ...

where # sets the number of plotting windows and the arguments $ <$wind1$ >$ ... should each be replaced with a valid surface plotting command argument, which will be applied to the respective window. The arguments $ <$wind1$ >$ ... must be of the form $ <$arg$ >$ {# | #:# | ALL}, where $ <$arg$ >$ is any of the SPLOT arguments listed above, and where # specifies a dataset number (default dataset number is 1), or #:# represents an inclusive range of datasets.

In addition, 2-D plotting within Sherpa may be performed using the REGION-PROJECTION and REGION-UNCERTAINTY commands:

REGION-PROJECTION creates a contour plot of confidence regions, computed using the PROJECTION algorithm (See Chapter 1, Section 1.61). The command REG-PROJ is an abbreviated equivalent:

sherpa> REGION-PROJECTION $ [$$ <$dataset_range$ >$ | ALLSETS$ ]$ $ <$modelname$ >$.{$ <$para mname$ >$ | $ <$#$ >$} $ <$modelname$ >$.{$ <$paramname$ >$ | $ <$#$ >$}

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 for REGION-PROJECTION is all datasets (ALLSETS).

$ <$modelname$ >$ is the name that has been given to a model component by the user. Notice that either $ <$paramname$ >$ or $ <$#$ >$ may be used to specify the two thawed parameters to be analyzed. See Chapter 1, Section 1.66 for further information regarding this command.

REGION-UNCERTAINTY creates a contour plot of confidence regions, computed using the UNCERTAINTY algorithm (See Chapter 1, Section 1.85). The command REG-UNC is an abbreviated equivalent:

sherpa> REGION-UNCERTAINTY $ [$$ <$dataset_range$ >$ | ALLSETS$ ]$ $ <$modelname$ >$.{$ <$par amname$ >$ | $ <$#$ >$} $ <$modelname$ >$.{$ <$paramname$ >$ | $ <$#$ >$}

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 for REGION-UNCERTAINTY is all datasets (ALLSETS).

$ <$modelname$ >$ is the name that has been given to a model component by the user. Notice that either $ <$paramname$ >$ or $ <$#$ >$ may be used to specify the two thawed parameters to be analyzed. See Chapter 1, Section 1.67 for further information regarding this command.

Examples:

  1. Display 2-D data with a contour plot: 
    sherpa> READ DATA 2 example2D.dat ASCII 1 2 3
sherpa> CPLOT DATA 2
    The last command plots dataset number 2 as a contour plot. Dataset number 2 must be a 2-D dataset.

  2. Display 2-D data with a surface plot: 
    sherpa> READ DATA 2 example2D.dat ASCII 1 2 3  
sherpa> SPLOT DATA 2
    The last command plots dataset number 2 as a surface plot. Dataset number 2 must be a 2-D dataset.

  3. Determine 1- and 2-sigma confidence regions for a fit: 
    sherpa> ERASE ALL
sherpa> READ DATA example1.dat
sherpa> PARAMPROMPT OFF
sherpa> SOURCE = POLYNOM1D[my]
sherpa> THAW my.c1 my.c2
sherpa> my.c0.min = -10
sherpa> FIT
sherpa> REGION-PROJECTION.nsigma = 2
sherpa> REGION-PROJECTION.expfac = 4
sherpa> REGION-PROJECTION my.c0 my.c2
Region-Projection: optimization reset to Levenberg-Marquardt.
                   computing grid size from covariance...done.
Region-Projection: outer grid loop 20% done...
Region-Projection: outer grid loop 40% done...
Region-Projection: outer grid loop 60% done...
Region-Projection: outer grid loop 80% done...
Minimum: 0.255412
Levels are: 2.55141 6.43641

  4. Determine 1-, 2-, 3-, and 4-sigma confidence regions for a fit: 
    sherpa> ERASE ALL
sherpa> READ DATA example1.dat
sherpa> PARAMPROMPT OFF
sherpa> SOURCE = POLYNOM1D[my]
sherpa> THAW my.c1 my.c2
sherpa> my.c0.min = -15
sherpa> FIT
sherpa> REGION-UNCERTAINTY.nsigma = 4
sherpa> REGION-UNCERTAINTY my.c0 my.c2
Region-Uncertainty: computing grid size...done.
Region-Uncertainty: outer grid loop 20% done...
Region-Uncertainty: outer grid loop 40% done...
Region-Uncertainty: outer grid loop 60% done...
Region-Uncertainty: outer grid loop 80% done...
Minimum: 0.255412
Levels are: 2.55141 6.43641 12.0854 19.5904

Additional CPLOT, SPLOT, REGION-PROJECTION, and REGION-UNCERTAINTY command examples may be found in Chapter 1, Sections 1.22, 1.78, 1.66, and 1.67 respectively.


2.4.1 ChIPS 2-D Plot Controls

All ChIPS commands are available from within Sherpa (note, however, that axis limits on contour and surface plots may not be modified). See the ChIPS Reference Manual for complete ChIPS command definitions and further examples.

Note that ChIPS plot control commands require that a REDRAW command be issued, in order for the plot display to be updated.

Examples:

  1. Plot data as a contour plot and change contour levels: 
    sherpa> DATA data/example2D.dat ASCII 1 2 3
sherpa> CPLOT DATA
sherpa> LEVELS 3 5 20 100
sherpa> REDRAW
    In this example, a 2-D dataset is input to Sherpa and then displayed as a contour plot. The ChIPS LEVELS command changes the contour levels to 3, 5, 20, and 100 for contour lines 1 thru 4, respectively.

  2. Plot data as a surface plot and label the z-axis: 
    sherpa> SPLOT DATA
sherpa> ZLABEL "This is the Z Axis"
sherpa> REDRAW
    After a surface plot has been made, a label is added to the z-axis with the ChIPS command ZLABEL.

next up previous
Next: 3. Sherpa Filtering Up: Sherpa Reference Manual Previous: 1. Sherpa Commands
cxchelp@head.cfa.harvard.edu