NAME
mxevtfilter
USAGE
mxevtfilter rootname detector evtlist gtilist src_regfile bkg_regfile
DESCRIPTION
Using a list of event files and matching GTIs, create a number of output data products
including event files and images. Specifically, it makes
- a single event file which contains all events from all cameras, plus
GTI extensions, one for each camera;
- individual camera event files for combinations of field-of-view (FOV), high voltage states,
and source or background regions;
- image files for each requested energy band;
- (GSC ONLY) event files filtered for each of 1650 V and 1550 V settings;
- [OPTIONAL] GTI files based on scan condition filters
In addition to these, ASCII file lists and an image mask are generated intended for
inputs to other MAXI processing tools.
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 create a new GTI that selects interval in which the solar panels do not obstruct the field of
view, the expression filter would be set:
expression = 'obscured_sp==0'
To create a GTI that also exlcudes 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'
Note, however, the resulting GTI files (named with the suffix '_tot.gti') are created, but NOT
applied to filter the data. They are availabel to be used for other downstream processing,
but the setting of expression filters does not filter any of the output event or image
products made by 'mxevtfilter'.
PARAMETERS
- rootname [string]
-
The prefix on all output file names.
- detector [string]
-
The name of the MAXI detector. Should be one of 'gsc_low', 'gsc_med', or 'ssc'
('ssc_med' is equivalent to 'ssc').
- evtlist [string]
-
A list of input 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.
- gtilist [string]
-
A list of input GTI 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.
- (hvlist = "CALDB") [string]
-
A list of high voltage state settings for GSC.
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.
If set to "CALDB" (default), the high voltage history is obtained by
reading the MAXI calibration database.
Ignored if the detector is SSC.
- (simbkglist = "NONE") [string]
-
A list of the simulated background 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.
If not using simulated background, set to "NONE" (default).
- src_regfile [filename]
-
The name of the ds-9 compatible source region file.
- bkg_regfile [filename]
-
The name of the ds-9 compatible background region file.
Set to "NONE" if not using background.
- (eband_fname = "REFDATA") [filename]
-
The name of the ASCII file containing the energy band settings.
Reads the default settings (bands at 2-6 and 6-20 keV for GSC,
or a single band 0.7-7 kev for SSC) from the MAXI reference data
if set to "REFDATA" (default).
- (scancondlist = "NONE") [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.
Ignored if set to "NONE" (default).
- (expression = ' ') [string]
-
A filter expression for selecting GTI based on flags found in the scan
condition files. If no conditions are set, no filtering will be done.
Ignored if 'scancondlist="NONE"'. If set, the scan condition
files are read and GTI are generated based on the selection. These
GTI files are named based on the prefix setting, camera ID, and the
suffix "_tot.gti".
- (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.
- (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). 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 "mxevtfilter.log". If preceded by the "!", 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, but not suitable for routine operation.
Default is "no".
- (mode = ql) [string ql|hl|q]
- Mode to query the parameter file.
Acceptable values include: "ql" (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).(Optional)
EXAMPLES
Given a list of input event files and matching GTIs for time intervals when the
source is in the field of view, generate:
- individual camera event files, filtered on the input GTIs (named crab_g[#]_fov.evt),
plus an ASCII file containing a list of these files (crab_gsc_fov.list);
- a master event file containing all events in the FOV plus GTI extensions, one for
each camera (crab_gsc.evt);
- an image file with the first energy band (2-6 keV) in the primary array image, and
the second (6-20 keV) in the first image extension, in which the energy bands are
set using default reference data;
- a mask file (crab_gsc_mask.fits) containing image arrays for source and
background regions projected into the image plane;
- individual camera event files, filtered on the input GTIs and the source
or background region files (crab_g[#]_fov_[src|bkg].evt) and matching ASCII lists
of these files (crab_gsc_fov_[src|bkg].list);
- individual camera event files, filtered on the input GTIs and voltage states,
and matching ASCII lists of these files (crab_gsc_fov_[1550|1650]v.list);
- GTIs for each FOV merged with high voltage GTIs from CALDB
(crab_g[#]_fov_[1550|1650]v.gti);
- source and background event files for each voltage state
and a list of these files is also made
named crab_gsc_fov_[1550|1650]v.list;
No scan condition filter GTIs are generated as they were not requested.
mxevtfilter rootname=crab detector=gsc_low evtlist=crab_g1.evt,crab_g2.evt,crab_g7.evt \
gtilist=crab_g1_fov.gti,crab_g2_fov.gti,grab_g7_fov.gti hvlist=CALDB eband_fname=REFDATA \
src_regfile=crab_src.reg bkg_regfile=crab_bkg.reg
SEE ALSO
hpextract, mxextract, mxevtgti, mxpipeline
LAST MODIFIED
July 2025 (mxevtfilter v0.62b)