HEADAS help file for mxpha

NAME

mxpha

USAGE

mxpha rootname srcevt_list bkgevt_list src_outfile bkg_outfile maskfile scancond_list

DESCRIPTION

Read a list of source and (if requested) background MAXI event files to generate source and background spectra, using an optional filter for events based on input scan condition settings.

Construction of scan condition filter expression

The syntax for setting a scan condition filter is identical to the logic used in the ftselect tool: the expression parameter acts as a filter to select only time intervals matching those selection criteria.
In MAXI scan condition files, there are columns (one row for each GTI/scan interval) with START, STOP, a series of byte-format scan condition flags set to 0 (no) or 1 (yes), and high voltage setting as an integer (854 for 1650 V; 803 for 1550 V. These codes match those used in MAXI CALDB high voltage history files) The typical byte-format flag columns for GSC are:

incomplete_scan_src
incomplete_scan_bkg
out_detector_src
out_detector_bkg
in_san_src (i.e. the source seen by the anode wires (no internal instrument obstruction)
in_san_bkg (i.e. the background is not obscured by internal instrument obstruction)
obscured_sp (i.e. not obscured by the ISS solar panels)
obscured_ss (i.e. not obscured by a docked space shuttle)

To filter on scan conditions when generating spectra, the expression parameter is set to include only intervals that meet the scan condition settings. For example, to create a spectra file that only includes intervals in which the solar panels do not obstruct the field of view, the expression filter would be set:

    expression = 'obscured_sp==0'

To also exlcude intervals where the field of view is blocked by a docked space shuttle, these conditions would be combined:

    expression = 'obscured_sp==0 && obscured_ss==0'

If the parameter scancond_list is set (i.e. not blank or "NONE"), but no expression is set, mxpha will use default filters, depending on the instrument settings. These area:

GSC with background:
```
'out_detector_src==0 && out_detector_bkg==0 && in_san_src==0 && in_san_bkg==0 && obscured_sp==0 && obscured_ss==0'
```
(only include data where the scan includes background and source, there are no internal obstructions from the GSC central wire, and the field of view is not obstructed by the solar panels or a docked space shuttle)
GSC with no background:
```
'out_detector_src==0 && in_san_src==0 && obscured_sp==0 && obscured_ss==0'
      
```
(as with background, but without the background scan filter settings)
SSC with background:
```
	'out_detector_src==0 && out_detector_bkg==0'
	
```
(only include scans with the source and background included: SSC does not have the internal obscuring central wire in GSC, and the instrument's field of view is never obscured by the solar panels nor the docked space shuttle).
SSC without background:
```
	'out_detector_src==0'
      
```
(i.e. as with background above, but background related terms dropped).

These default expression filters are the mostly commonly useful, but can be overridden by explicitly setting the expression filter parameter if desired.

PARAMETERS

rootname [string]

The prefix on all output files.

srcevt_list [string]

A list of source event files. This may be a comma-delimited list, or the name of a text file containing a list of files, one per line, preceded by an '@' character.

bkgevt_list [string]

A list of background event files. This may be a comma-delimited list, or the name of a text file containing a list of files, one per line, preceded by an '@' character. Set to "NONE" or blank if no background is used.

maskfile [filename]

The name of the FITS image file containing image projection plane masks for the source and background regions and FITS keywords to define the total number of pixels in each region. Ignored if there are no background event files.

(leapsecfile = "REFDATA") [string]

If set to "REFDATA" (default), use the built-in reference file for defining leap seconds. If set to "CALDB", use the reference file in the MAXI calibration database. Otherwise, use the specified file name.

scancond_list [string]

A list of scan condition files. This may be a comma-delimited list, or the name of a text file containing a list of files, one per line, preceded by an '@' character. Set to "NONE" if not filtering the raw scan data for scan condition settings.

(expression = ' ') [string]

A filter expression for setting and using GTI for spectra based on flags found in the scan condition files. If no conditions are set (default), the default scan conditions will be used:

GSC: include only data containing source and background (if selected) in the detector, not obcured by the central wire, and not obscured by the ISS solar panels nor the docked space shuttle at any time during the scan;
SSC: include only data containing the source and background (if selected).

Note that if there is no background set, the filter expressions specific to background are not used. Ignored if no scan condition files are specified.

(cleanup = no) [boolean]

Determines whether to delete temporary files (yes/[no]).

(clobber = no) [boolean]

Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]

Sets the amount of output from the code. Values range from 0 (little to no output) to 3 (verbose: provides considerable output). The default value of 1 provides basic details as code runs.

(logfile = "!DEFAULT") [string]

Record output from running this tool. If set to DEFAULT, the output logfile will be named "mxpha.log". If preceded by "!", any existing file with the same name will be overwritten; otherwise this output will be appended to any existing file.

(history = yes) [boolean]

Records tool parameters in HISTORY ([yes]/no).

(debug = no) [boolean]

If set to "yes", the code will provide detailed logging of variables and settings as the code runs in considerable detail. This can be useful when debugging features in the code or deciphering unexpected error conditions. Default is "no".

(mode = ql) [string ql|hl|q]

Mode to query the parameter file. Acceptable values include: "ql" (query and learn/remember)(default), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).

EXAMPLES

Generate 1650 V MAXI GSC source and background spectra using the default scan condition filters, and generate the associated GTI. The files 'crab_gsc_1650v_src.list' and 'crab_gsc_1650v_bkg.list' contain the names of event files for each camera present from the GSC instrument at 1650 V. The file 'crab_gsc_scancond.list' contains a list of scan condition files for each GSC camera present.
```
mxpha rootname=crab_g srcevt_list=@crab_gsc_1650v_src.list bkgevt_list=@crab_gsc_1650v_bkg.list \
  scancond_list=@crab_gsc_scancond.list maskfile=crab_gsc_mask.fits chatter=3 logfile="\!DEFAULT"
```
The output will be a spectra file 'crab_gsc_1650v_src.pi', a background spectra file 'crab_gsc_1650v_bkg.pi', a set of GTI with names 'crab_g#_1650v_spec.gti' (where # is a value 0..b), and an output log file named 'mxpha.log'. If a previous log file existed, it was clobbered by this new log. The chatter setting provides a highly detailed level of output.

Given a single camera event file for the SSC horizontal instrument for source and background, and a single matching SSCH scan condition file, generate source and background spectra using built-in default scan condition filters, and generate the associated GTI. Provide detailed output to the terminal and record it in a log file 'mxpha.log'.
```
mxpha rootname=crab_s srcevt_list=crab_sh_src.evt bkgevt_list=crab_sh_bkg.evt \
  scancond_list=crab_sh_scancond.fits maskfile=crab_ssc_mask.img chatter=3 logfile="\!DEFAULT"
```
The output will be a spectra file 'crab_sh_src.pi', a background spectra file 'crab_sh_bkg.pi', a GTI file 'crab_sh_spec.gti', and a log file named 'mxpha.log', clobbering any previous log with the same name.

CAVEATS

When processing GSC data, spectra should be generated with this tool for only a single high voltage state at time. The tool presumes input source event files will have names containing '1650v' or '1550v' ('854' or '803' respectively are also accepted) to indicate which voltage was used. Failure to comply with this convention may result in unintended consequences.

LAST MODIFIED

July 2025 (mxpha v0.72)