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.