[{"data":1,"prerenderedAt":22},["ShallowReactive",2],{"analysis-playbook-maxi-sdtdata-quickguide":3},{"@context":4,"@type":5,"name":6,"articleBody":7,"proficiencyLevel":8,"dependencies":9,"programmingLanguage":11,"keywords":12,"citation":14,"about":18},"https:\u002F\u002Fschema.org","TechArticle","MAXI Quick-Start Guide","## MAXI Quick-Start Guide\n\nA quick instruction of FTOOLS-based standard analysis with MAXI archive data obtained from DARTS at ISAS.\nUsers basically need to run only 2 scripts, **mxdownload_wget** for data download, and **mxpipeline** for data analysis.\n\nFor more detailed information about MAXI ftools, please read the [MAXI Software Usage Guide](https:\u002F\u002Fheasarc.gsfc.nasa.gov\u002Fdocs\u002Fmaxi\u002Fanalysis\u002Fmaxi_software_usage_20250915.pdf) at NASA\u002FGSFC.\n\n---\n\n### Installation of HEASoft and CALDB\n\nThe [HEASoft software](https:\u002F\u002Fheasarc.gsfc.nasa.gov\u002Fdocs\u002Fsoftware\u002Flheasoft\u002Fdownload.html) version 6.36 or later and [the MAXI CALDB files](https:\u002F\u002Fheasarc.gsfc.nasa.gov\u002Fdocs\u002Fmaxi\u002Fcaldb\u002Findex.html) are required for the MAXI data analysis.\n\nThe CALDB files are also available in the [CALDB mirror](https:\u002F\u002Fdata.darts.isas.jaxa.jp\u002Fpub\u002Fmirror\u002Fcaldb\u002Fmaxi\u002F) at DARTS. Instructions for installing CALDB is available at [the CALDB installation page](https:\u002F\u002Fheasarc.gsfc.nasa.gov\u002Fdocs\u002Fheasarc\u002Fcaldb\u002Fcaldb_install.html).\n\n### Download MAXI Data\n\nAt your working directory (e.g. `cd $HOME\u002Fanalysis\u002F`), run the script **mxdownload_wget** as follows:\n\n```\nmxdownload_wget --coordinates RA,DEC --dates YYYY-MM-DD,YYYY-MM-DD   [OPTIONS]\n```\n\n#### Example 1 : List the data for Crab from 2010-01-01 to 2010-01-31 for all instruments.\n\n```\nmxdownload_wget --coordinates 83.633,22.015 --dates 2010-01-01,2010-01-03 --dryrun\n```\n\nThe 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.\n\n#### Example 2 : Download the data for Crab from 2010-01-01 to 2010-01-03 for all instruments from DARTS.\n\n```\nmxdownload_wget --coordinates 83.633,22.015 --dates 2010-01-01,2010-01-03 --instrument all -uri https:\u002F\u002Fdata.darts.isas.jaxa.jp\u002Fpub\u002Fmaxi\u002Fmxdata\u002F\n```\n\nThis 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\u002F` sub-directory.\n\n#### Example 3 : Download the SSC data only for the radius of 10.0 degrees from HEASARC.\n\n```\nmxdownload_wget --instrument ssc_med --coordinates 83.633,22.015 --date_from 2010-01-01 --date_to 2010-01-03 --radius 10.0\n```\n\nUsers can specify a radius and an instrument mode with options, `--radius` (default: 8.0 deg) and `--instruments` (default: gsc_low), respectively.\nIf you omit the \"-uri\" option, the data are downloaded from HEASARC.\n\nYou can view a concise on-line help by `fhelp mxdownload_wget` or the command `mxdownload_wget -help`.\n\n### MAXI data structure\n\nThe following is the directory structure created by **mxdownload_wget**.\n\n#### gsc_low, gsc_med\n\n```\nCWD -+- obs -+- MJD55000 --+- MJD55000 --+- auxil --+- mx_mjd[MMMMMM].att.gz \n             +- MJD56000   +- MJD55001   |          +- mx_mjd[MMMMMM].iac.gz \n             +- MJD57000   +- MJD55002   |          +- mx_mjd[MMMMMM].iat.gz\n                .....      +- MJD55003   |          +- mx_mjd[MMMMMM].isa.gz\n                              .....      |          +- mx_mjd[MMMMMM].isp.gz \n                           +- MJD55999   |          +- mx_mjd[MMMMMM]_mkf.gz\n                                         |          +- mx_mjd[MMMMMM]_orb.gz\n                                         |          +- mx_mjd[MMMMMM]_att.hk.gz\n                                         |          +- mx_mjd[MMMMMM]_gsc_hk.gz\n                                         |          +- mx_mjd[MMMMMM]_gsc[C]_low.gti.gz\n                                         |          +- mx_mjd[MMMMMM]_gsc[C]_med.gti.gz\n                                         +- events -+- gsc_low --- mx_mjd[MMMMMM]_gsc_low_[NNN].evt.gz \n                                                    +- gsc_med --- mx_mjd[MMMMMM]_gsc_med_[NNN].evt.gz\n```\n\n#### ssc_med\n\n```\nCWD -+- obs -+- MJD55000 --+- MJD55000 --+- auxil --+- mx_mjd[MMMMMM].att.gz \n             +- MJD56000   +- MJD55001   |          +- mx_mjd[MMMMMM].iac.gz \n             +- MJD57000   +- MJD55002   |          +- mx_mjd[MMMMMM].iat.gz\n                .....      +- MJD55003   |          +- mx_mjd[MMMMMM].isa.gz\n                              .....      |          +- mx_mjd[MMMMMM].isp.gz \n                           +- MJD55999   |          +- mx_mjd[MMMMMM]_mkf.gz\n                                         |          +- mx_mjd[MMMMMM]_orb.gz\n                                         |          +- mx_mjd[MMMMMM]_att.hk.gz\n                                         +- events -+- ssc_med --- mx_mjd[MMMMMM]_ssc[D]_med_[NNN].evt.gz \n```\n\nCWD 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).\n\n#### HEALPix\n\n[Healpix](https:\u002F\u002Fhealpix.sourceforge.net\u002F) is the library to define the regions on the sky, dividing the entire sky into regions with a similar area-size to one another.\n\nMAXI 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.\nAlso, there is a lack of data for different reasons: MAXI shutdown, downlink problems, processing errors etc.\n\n### Analyze MAXI Data\n\nNow you are ready to make data analysis using the raw MAXI data in your local disk with **mxpipeline**.\n\n```\nmxpipeline RA DEC TSTART TSTOP [OPTIONS]\n```\n\nThe **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.\nWhen 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.\n\nThe ftool help is given by `fhelp mxpipeline` or read [MAXI Software Usage Guide](https:\u002F\u002Fheasarc.gsfc.nasa.gov\u002Fdocs\u002Fmaxi\u002Fanalysis\u002Fmaxi_software_usage_20250915.pdf) for more details.\n\n#### Example 1 : Analyze the GSC-low data for Crab.\n\n```\nmxpipeline ra=83.633 dec=22.015 tstart=2010-01-01 tstop=2010-01-03 object=crab\n```\n\nThis will create the gsc_low science products of spectrum files, response files, and light-curves.\nIn this example, **mxpipeline** should be run at your working data-directory, which contains `obs\u002F`. The science products are created in the directory `.\u002Fproducts\u002F` or, user-specified name by the parameter, `--outpath`.\n\n#### Example 2 : Analyze the GSC-med data for Crab specifying regions and energy bands.\n\n```\nmxpipeline ra=83.633 dec=22.015 tstart=2010-01-01 tstop=2010-01-03 object=crab \\\n  detector=gsc_med  src_regfile=src.reg bkg_regfile=bkg.reg eband_fname=ebands_file.txt\n```\n\nThe optional parameters in the command, `detector`, `src_regfile`, `bkg_regfile`, and `eband_fname` are described below.\n\n### Commonly used options of mxpipeline\n\n#### Detector\n\nThe GSC has 2 data types of `gsc_low` and `gsc_med`, while the SSC has only `ssc_med`.\nTo perform both GSC and SSC processing, specify detector=\"gsc_low,ssc\" or \"gsc_med,ssc\".\nThe option with detector=\"gsc_low,gsc_med\" is not supported.\nOur recommendation is `gsc_low`, which is the default.\n\n#### Region files\n\nYou can set the source and the background region files by optional parameters, `src_regfile` and `bkg_regfile`.\nThe region-file format is the ds9 format in plain text with the fk5 coordinate system in degrees.\nWhen saving a region file in ds9, be careful to select coordinates **in degrees**.\nCurrently, acceptable shape of the source region is a simple \"circle\", and the background region is \"circle - circle\".\nThe background region has to be within the search radius of the observed events.\n\nExample for the source region file:\n\n```\n# Region file format: DS9 version 4.1\nglobal 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\nfk5\ncircle(83.633,22.015,6000\")\n```\n\nExample for the background region file:\n\n```\n# Region file format: DS9 version 4.1\nglobal 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\nfk5\ncircle(83.633,22.015,108000\")\n-circle(83.633,22.015,7200\")\n```\n\n#### Energy-band filter\n\nMulti-band light-curves can be generated and stored in multiple extensions in a single output FITS file.\nThe default energy bands are 2.0–6.0 and 6.0–20.0 keV for GSC, 0.7–7.0 keV for SSC.\nIf 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.\n\nExample for GSC:\n\n```\n# GSC\n# conversion 50 eV\u002Fch\n#  min_ch    max_ch  min_ene   max_ene    \n40        120     2.0       6.0\n120       400     6.0       20.0\n```\n\nExample for SSC:\n\n```\n# SSC\n# conversion 3.65 eV\u002Fch\n#  min_ch    max_ch  min_ene   max_ene    \n192       1918    0.7       7.0\n```\n\n### Data products created by mxpipeline\n\n**gsc_low, gsc_med**\n\n```\nCWD -+- obs +- mxpipeline.log \n     +- products -+- [Object]_bkg.reg \n     |            +- [Object]_gsc_bin.lc\n     |            +- [Object]_gsc_bkg.pi\n     |            +- [Object]_gsc_src.pi     \n     |            +- [Object]_gsc.evt\n     |            +- [Object]_gsc.img\n     |            +- [Object]_gsc.rmf\n     |            +- [Object]_src.reg \n     +- trend ----+- iatlist.fits \n                  +- isalist.fits \n                  +- isplist.fits \n                  +- vclist.fits\n```\n\n**ssc_med**\n\n```\nCWD -+- obs +- mxpipeline.log \n     +- products -+- [Object]_bkg.reg \n     |            +- [Object]_sh.rmf\n     |            +- [Object]_src.reg\n     |            +- [Object]_ssc_bin.lc\n     |            +- [Object]_ssc_bkg.pi \n     |            +- [Object]_ssc_src.pi     \n     |            +- [Object]_ssc.evt\n     |            +- [Object]_ssc.img\n     |            +- [Object]_ssc.rmf\n     |            +- [Object]_sz.rmf\n     +- trend ----+- iatlist.fits \n```\n\nDuring the processing, many intermediate files are created in `products\u002F` (or user-specified name by `outpath`) directory.\nThey are automatically deleted after the processing in default, unless the parameter `cleanup=no` is specified.\nSome auxiliary files are also created in the directory `trend\u002F`.\n\n---\n\nThe MAXI team  \nPlease send questions, comments, and bug reports to: [maxihelp@ml.ac.jaxa.jp](mailto:maxihelp@ml.ac.jaxa.jp)\n","intermediate",[10],"Heasoft","Python",[13],"MAXI",[15],{"@type":16,"url":17},"SoftwareApplication","https:\u002F\u002Fheasarc.gsfc.nasa.gov\u002Fdocs\u002Fsoftware\u002Flheasoft\u002F",[19],{"@type":20,"name":21},"Dataset","darts:maxi-sdtdata",1777270238277]