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