What is the difference between the 'load', 'read', and 'unpack' Sherpa commands?

There are several Sherpa functions which can be used to load user data into a Sherpa session. For example, the 'load', 'read', and 'unpack' commands, which have similar, but distinct, functionality:

• load - the standard way of reading data files into Sherpa and assigning them to data set IDs; this is equivalent to the "read" command in Sherpa 3.4
• unpack - these are low-level Sherpa commands used to read data files; they are more general than "load" and do not assign data set IDs to files that are read.
• read - these are Crates low-level commands to read data files; they can be used in Chips, without Sherpa open.

The filetype-specific 'load' functions load 1-D data from a user-specified file into a Sherpa session and assign it to an appropriate Sherpa data set ID. The most commonly used 'load' functions are load_pha, load_arf, and load_rmf, which load into Sherpa a specified PHA data set and the corresponding ARF and RMF response files, respectively.

ciao% sherpa
  
sherpa> myfile=load_pha("646_meg_p1_bin10.pha")                   
statistical errors were found in file '646_meg_p1_bin10.pha' 
but not used; to use them, re-read with use_errors=True
read background_up into a dataset from file 646_meg_p1_bin10.pha
read background_down into a dataset from file 646_meg_p1_bin10.pha

sherpa> load_arf("646_meg_p1.arf")                                  

sherpa> load_rmf("646_meg_p1.rmf")                                  

sherpa> show_data()                                                 
Data Set: 1
Filter: 0.2957-12.3370 Energy (keV)
Noticed Channels: 1.0-8192.0
name           = 646_meg_p1_bin10.pha
channel        = Float64[8192]
counts         = Float64[8192]
staterror      = None
syserror       = None
bin_lo         = Float64[8192]
bin_hi         = Float64[8192]
grouping       = Int16[8192]
quality        = Int16[8192]
exposure       = 47341.6434672
backscal       = 1.0
areascal       = 1.0
grouped        = True
subtracted     = False
units          = energy
response_ids   = [1]
background_ids = [1, 2]

[rest of output omitted]

In this example, the PHA file 646_meg_p1_bin10.pha is automatically assigned to data set 1 ('id=1'), and the ARF and RMF are assigned to the first instrument response for data set 1 ('resp_id=1'). Note that the background data sets associated with the specified PHA file are automatically loaded and assigned to background IDs (bkg_id=1, bkg_id=2, etc.), since the background filenames are recorded in the header of the PHA file.

The full list of 'load' commands can be accessed by typing " *load*? " at the Sherpa prompt.

The 'read' commands are similar to the 'load' commands in that they are used to load spectral data from a PHA FITS file, tabular data from a FITS file, or a column-based text file into a Sherpa session. However, instead of assigning the loaded file to a Sherpa data set ID, the 'read' commands load the data into a "crate", which can be thought of as a filetype-specific variable.

sherpa> myfile=read_pha("data1.pi")                                   

sherpa> print myfile                                                  
<DataPHA data set instance 'data1.pi'> 

sherpa> show_data()                                                   

sherpa>

sherpa> print get_col_names(myfile)                                   
['CHANNEL' 'PI' 'COUNTS' 'STAT_ERR' 'COUNT_RATE' 'GROUPING' 'QUALITY'
 'GRP_NUM' 'CHANS_PER_GRP' 'GRP_DATA' 'GRP_STAT_ERR']

Here the data is input, but not assigned to a Sherpa data set, as show_data prints an empty line.

The 'unpack' commands can be used to load data from a crate or FITS file into a Sherpa data object:

sherpa> myfile=unpack_pha("data1.pi")                   
statistical errors were found in file 'data1.pi'
but not used; to use them, re-read with use_errors=True

sherpa> print myfile                                    
[<DataPHA data set instance 'data1.pi'>]

sherpa> show_data()                                  

sherpa>

sherpa> set_data(myfile[0])

sherpa> show_data()
Data Set: 1
Filter: 0.1248-12.4100 Energy (keV)
Noticed Channels: 1-1024
name           = data1.pi
channel        = Float64[1024]
counts         = Float64[1024]
staterror      = None
syserror       = None
bin_lo         = None
bin_hi         = None
grouping       = Int16[1024]
quality        = Int16[1024]
exposure       = 38564.6089269
backscal       = 2.52643646989e-06
areascal       = 1.0
grouped        = True
subtracted     = False
units          = energy
rate           = True
plot_fac       = 0
response_ids   = [1]
background_ids = [1]

Here the data is input, but not assigned to a Sherpa data set, as show_data prints an empty line. The set_data command should be used to establish a data set from a Sherpa data object such as 'myfile'.

Users familiar with the CIAO Data Model should note the following:

• Crates reads one extension of the input file, not the whole data set. The file that is written out will only contain the block which was read.
• Crates does not retain the data subspace of the file.
• Crates does not retain HISTORY or COMMENT blocks from the input file.

Please refer to the Sherpa ahelp pages for a full description of each command, including examples of usage.