MAXI Quick-Start Guide
MAXI Quick-Start Guide
A quick instruction of FTOOLS-based standard analysis with MAXI archive data obtained from DARTS at ISAS.
Users basically need to run only 2 scripts, mxdownload_wget for data download, and mxpipeline for data analysis.
For more detailed information about MAXI ftools, please read the MAXI Software Usage Guide at NASA/GSFC.
Installation of HEASoft and CALDB
The HEASoft software version 6.36 or later and the MAXI CALDB files are required for the MAXI data analysis.
The CALDB files are also available in the CALDB mirror at DARTS. Instructions for installing CALDB is available at the CALDB installation page.
Download MAXI Data
At your working directory (e.g. cd $HOME/analysis/), run the script mxdownload_wget as follows:
mxdownload_wget --coordinates RA,DEC --dates YYYY-MM-DD,YYYY-MM-DD [OPTIONS]
Example 1 : List the data for Crab from 2010-01-01 to 2010-01-31 for all instruments.
mxdownload_wget --coordinates 83.633,22.015 --dates 2010-01-01,2010-01-03 --dryrun
The options --dryrun and --planonly are for dry-running (simulated run) and can be useful to see how it works and how many data files will be (attempted to be) downloaded. Data are not downloaded with either of them.
Example 2 : Download the data for Crab from 2010-01-01 to 2010-01-03 for all instruments from DARTS.
mxdownload_wget --coordinates 83.633,22.015 --dates 2010-01-01,2010-01-03 --instrument all -uri https://data.darts.isas.jaxa.jp/pub/maxi/mxdata/
This command download all the MAXI data (gsc_low, gsc_med, and ssc_med) that satisfy the specified conditions from the DARTS data archive. The data is stored at the newly-created obs/ sub-directory.
Example 3 : Download the SSC data only for the radius of 10.0 degrees from HEASARC.
mxdownload_wget --instrument ssc_med --coordinates 83.633,22.015 --date_from 2010-01-01 --date_to 2010-01-03 --radius 10.0
Users can specify a radius and an instrument mode with options, --radius (default: 8.0 deg) and --instruments (default: gsc_low), respectively.
If you omit the “-uri” option, the data are downloaded from HEASARC.
You can view a concise on-line help by fhelp mxdownload_wget or the command mxdownload_wget -help.
MAXI data structure
The following is the directory structure created by mxdownload_wget.
gsc_low, gsc_med
CWD -+- obs -+- MJD55000 --+- MJD55000 --+- auxil --+- mx_mjd[MMMMMM].att.gz
+- MJD56000 +- MJD55001 | +- mx_mjd[MMMMMM].iac.gz
+- MJD57000 +- MJD55002 | +- mx_mjd[MMMMMM].iat.gz
..... +- MJD55003 | +- mx_mjd[MMMMMM].isa.gz
..... | +- mx_mjd[MMMMMM].isp.gz
+- MJD55999 | +- mx_mjd[MMMMMM]_mkf.gz
| +- mx_mjd[MMMMMM]_orb.gz
| +- mx_mjd[MMMMMM]_att.hk.gz
| +- mx_mjd[MMMMMM]_gsc_hk.gz
| +- mx_mjd[MMMMMM]_gsc[C]_low.gti.gz
| +- mx_mjd[MMMMMM]_gsc[C]_med.gti.gz
+- events -+- gsc_low --- mx_mjd[MMMMMM]_gsc_low_[NNN].evt.gz
+- gsc_med --- mx_mjd[MMMMMM]_gsc_med_[NNN].evt.gz
ssc_med
CWD -+- obs -+- MJD55000 --+- MJD55000 --+- auxil --+- mx_mjd[MMMMMM].att.gz
+- MJD56000 +- MJD55001 | +- mx_mjd[MMMMMM].iac.gz
+- MJD57000 +- MJD55002 | +- mx_mjd[MMMMMM].iat.gz
..... +- MJD55003 | +- mx_mjd[MMMMMM].isa.gz
..... | +- mx_mjd[MMMMMM].isp.gz
+- MJD55999 | +- mx_mjd[MMMMMM]_mkf.gz
| +- mx_mjd[MMMMMM]_orb.gz
| +- mx_mjd[MMMMMM]_att.hk.gz
+- events -+- ssc_med --- mx_mjd[MMMMMM]_ssc[D]_med_[NNN].evt.gz
CWD refers to the current working-directory, (gsc_low, gsc_med, ssc_med) is the instrument_mode (data rate), [MMMMM] is the Modified Julian Day (MJD) in 5 digits, [C] is the counter-ID of the GSC (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, a, b), [D] is the detector-ID of the SSC (“h” or “z”), [NNN] is the HEALPix ID (000-767), respectively. The MAXI archive data is available since MJD55058 (=2009-08-15).
HEALPix
Healpix is the library to define the regions on the sky, dividing the entire sky into regions with a similar area-size to one another.
MAXI events are divided into 768 HEALPix regions of the all sky (each of about 7.3 deg × 7.3 sq deg). However, MAXI does not monitor all the 768 sky regions everyday, some data of some regions for some days are not available.
Also, there is a lack of data for different reasons: MAXI shutdown, downlink problems, processing errors etc.
Analyze MAXI Data
Now you are ready to make data analysis using the raw MAXI data in your local disk with mxpipeline.
mxpipeline RA DEC TSTART TSTOP [OPTIONS]
The mxpipeline requires 4 mandatory parameters. The center coordinates, RA and Dec given in degree (J2000). The format of TSTART and TSTOP is either YYYY-MM-DD or YYYY-MM-DDThh:mm:ss.
When only YYYY-MM-DD is specified, TSTART is identical to YYYY-MM-DDT00:00:00 and TSTOP is identical to YYYY-MM-DDT23:59:59.
The ftool help is given by fhelp mxpipeline or read MAXI Software Usage Guide for more details.
Example 1 : Analyze the GSC-low data for Crab.
mxpipeline ra=83.633 dec=22.015 tstart=2010-01-01 tstop=2010-01-03 object=crab
This will create the gsc_low science products of spectrum files, response files, and light-curves.
In this example, mxpipeline should be run at your working data-directory, which contains obs/. The science products are created in the directory ./products/ or, user-specified name by the parameter, --outpath.
Example 2 : Analyze the GSC-med data for Crab specifying regions and energy bands.
mxpipeline ra=83.633 dec=22.015 tstart=2010-01-01 tstop=2010-01-03 object=crab \
detector=gsc_med src_regfile=src.reg bkg_regfile=bkg.reg eband_fname=ebands_file.txt
The optional parameters in the command, detector, src_regfile, bkg_regfile, and eband_fname are described below.
Commonly used options of mxpipeline
Detector
The GSC has 2 data types of gsc_low and gsc_med, while the SSC has only ssc_med.
To perform both GSC and SSC processing, specify detector=“gsc_low,ssc” or “gsc_med,ssc”.
The option with detector=“gsc_low,gsc_med” is not supported.
Our recommendation is gsc_low, which is the default.
Region files
You can set the source and the background region files by optional parameters, src_regfile and bkg_regfile.
The region-file format is the ds9 format in plain text with the fk5 coordinate system in degrees.
When saving a region file in ds9, be careful to select coordinates in degrees.
Currently, acceptable shape of the source region is a simple “circle”, and the background region is “circle - circle”.
The background region has to be within the search radius of the observed events.
Example for the source region file:
# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
fk5
circle(83.633,22.015,6000")
Example for the background region file:
# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
fk5
circle(83.633,22.015,108000")
-circle(83.633,22.015,7200")
Energy-band filter
Multi-band light-curves can be generated and stored in multiple extensions in a single output FITS file.
The default energy bands are 2.0–6.0 and 6.0–20.0 keV for GSC, 0.7–7.0 keV for SSC.
If you want to change the energy bands, you prepare a plain text file that describes your desired (multiple) energy bands (up to three different energy bands) and run mxpipeline with eband_fname=[filename]. Note that the comment lines “# GSC” and “# SSC” lines are required.
Example for GSC:
# GSC
# conversion 50 eV/ch
# min_ch max_ch min_ene max_ene
40 120 2.0 6.0
120 400 6.0 20.0
Example for SSC:
# SSC
# conversion 3.65 eV/ch
# min_ch max_ch min_ene max_ene
192 1918 0.7 7.0
Data products created by mxpipeline
gsc_low, gsc_med
CWD -+- obs +- mxpipeline.log
+- products -+- [Object]_bkg.reg
| +- [Object]_gsc_bin.lc
| +- [Object]_gsc_bkg.pi
| +- [Object]_gsc_src.pi
| +- [Object]_gsc.evt
| +- [Object]_gsc.img
| +- [Object]_gsc.rmf
| +- [Object]_src.reg
+- trend ----+- iatlist.fits
+- isalist.fits
+- isplist.fits
+- vclist.fits
ssc_med
CWD -+- obs +- mxpipeline.log
+- products -+- [Object]_bkg.reg
| +- [Object]_sh.rmf
| +- [Object]_src.reg
| +- [Object]_ssc_bin.lc
| +- [Object]_ssc_bkg.pi
| +- [Object]_ssc_src.pi
| +- [Object]_ssc.evt
| +- [Object]_ssc.img
| +- [Object]_ssc.rmf
| +- [Object]_sz.rmf
+- trend ----+- iatlist.fits
During the processing, many intermediate files are created in products/ (or user-specified name by outpath) directory.
They are automatically deleted after the processing in default, unless the parameter cleanup=no is specified.
Some auxiliary files are also created in the directory trend/.
The MAXI team
Please send questions, comments, and bug reports to: maxihelp@ml.ac.jaxa.jp
