## 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](https://heasarc.gsfc.nasa.gov/docs/maxi/analysis/maxi_software_usage_20250915.pdf) at NASA/GSFC. --- ### Installation of HEASoft and CALDB The [HEASoft software](https://heasarc.gsfc.nasa.gov/docs/software/lheasoft/download.html) version 6.36 or later and [the MAXI CALDB files](https://heasarc.gsfc.nasa.gov/docs/maxi/caldb/index.html) are required for the MAXI data analysis. The CALDB files are also available in the [CALDB mirror](https://data.darts.isas.jaxa.jp/pub/mirror/caldb/maxi/) at DARTS. Instructions for installing CALDB is available at [the CALDB installation page](https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_install.html). ### 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](https://healpix.sourceforge.net/) 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](https://heasarc.gsfc.nasa.gov/docs/maxi/analysis/maxi_software_usage_20250915.pdf) 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](mailto:maxihelp@ml.ac.jaxa.jp)