NAME

mxdownload_wget : Search and retrieve the archived MAXI data for a given sky position and time interval

USAGE

mxdownload_wget --coordinates ra,dec -date_from tstart -date_to tstop

DESCRIPTION

Download MAXI data from the online archives to the local computer for a given coordinates and date range. The MAXI sky has been divided in 768 tiles (HEAL-IDs) with equal square degrees of 7.329 X 7.329 sq deg. The MAXI sky is organized by day and within a day, all tiles from the two instruments, GSC (med and low bit rate) and SSC (med bit rate for the horizontal and zenithal array), are stored together with the auxiliary files. For a given instrument/bit rate not all tiles have been created.

The script downloads the MAXI data organized in the same way of the MAXI archive: directories of one day with event data files and the necessary auxillary files for the MAXI data analysis. By default event data are downloaded only for the gsc_low. Data from other instrument/rate can be obtained using the option "instruments". To allow downstream software to work ,e.g. maxiproduct, the data retrived from the archive always include an additional day of data past the requested stop time.

The script allows to : a) only print the list of all expected files for region defined by the coordinates and the search radius within the time interval or to and coordinates , b) perform a dryrun by checking which files are on the remote archive server and last c) download the files. Data are not always available to create a file for a given instrument/bit rate/tile, therefore the a) option gives the list of all possible files regardless if data are available or not and b) option gives instead the list of files actually created and stored in the archive.

mxdownload_wget does not use the standard paramater file but instead options specified on the command line. If an option requires more than one argument, they should be separated by a comma without any space.

PARAMETERS

-coordinates ra,dec OR -x ra -y dec
These options allow to input the sky coordinates of the center region for the data search. The "coordinates" option has to be specified with a Right Ascension and Declination. Alternatively the coordinates may be specified with "x" option, for the Right Ascension and with the "y" option for the Declination. The "x" and "y" options need to be specified together. The Right Ascension and the Declination are J2000 coordinates in degrees.

-dates start,stop OR -date_from start -date_to stop
These options allow to input the time interval for the data search. The "dates" option has to be specified with a start time and end time. Alternatively the start and stop time may be specified with "date_from" option, for the start time and with the "date_to" option for the stop time. The "date_from" and "date_to" options need to be specified together. The start and stop time may be specified as YYYY-MM-DD (e.g. 2010-10-01) or as a Modify Julian Day (MJD, e.g. 55470).

-radius
This option allows to specify the search radius, in degree, around the RA and Dec specified with the coordinates options. If radius is not specified, the script uses a default radius set to 8 deg.

-instrument
This option allows to specify the data to download per instrument/bit rate. The allowed options are: gsc_med, gsc_low, ssc_med and all. They are to download the GSC medium bit rate data , GSC low bit rate data , SSC medius bit rate data or all (the data from GSC med/low and SSC medium) respectively. Therefore -instrument gsc_low,gsc_med,ssc_med is equivalent to -instrument all. If instrument is not specified, the script only download the gsc_low data.

-uri
The MAXI data are in the public archive of DARTS and HEASARC. This option allows to specify the url to wheere to download the data. The possible url are : https://www.darts.isas.jaxa.jp/pub/maxi/mxdata/ for the DARTS archive or https://heasarc.gsfc.nasa.gov/FTP/maxi/data/ for the HEASARC archive. If the option is not specified
https://heasarc.gsfc.nasa.gov/FTP/maxi/data/
is the default url.

-localdir
This option allows to specify a local directory to where stored the data. If the local directory does not exist the script gives and error. If it is not specified, the default is the current directory.

-chatter
This option allows to specify the level of chatter on the screen. The allowed values range from 0 (quiet) to 5 (very talkative). The default chatter level is 3.

-clobber
If this option is specified, the data files in the specific local directory previously downloaded for a specific search are removed. If not specified the clobber is set to false, e.g. no data file are removed.

-planonly
If this option is specified, the script only lists all possible files associated to the search regardless if data actually exists. Data are actually not downloaded if planonly or dryrun are specified.

-dryrun
If this option is specified, the script only lists the files associated to the search that exists in the archive. If some of the data files are in the local directory already also print a message to identify the file already on disk. Data are actually not downloaded if planonly or dryrun are specified.

-debug
If this option is specified, the debugging outputs are printed on the screen and temporary files are not deleted.

-auxilall
By default only a subset of the auxiliary files are retrived with the science data. This set includes the attitude and orbit data, iss ancillary (a, p) and a make filter file. If this option is specified additional auxiliary data are downloaded. These are : gsc housekeeping; ssch and sscz (e and dp) housekeeping; ssch ans sscz make filter file.

-help
This option allows to print the help for the script on teh screen. Provides a man page on the screen.

EXAMPLES

Example 1:

mxdownload_wget.pl -coordinates 83.633083,22.0145 -date_from 2010-01-01 -date_to 2010-01-02 --dryrun 
Perform a dry run (list the files, but do not download them) for R.A. 83.633083 Dec 22.0145 (J2000 equinox) between the dates Jan 1 and 2 in 2010. Since no instrument was specified, only the gsc_low instrument/mode will be listed. The code will also list the standard auxillary files expected to go with these data, with 13 event files which all lie within 8.0 degrees of the sky coordinates. Not specifying the uri (HTTPS address for the data archive from which to get MAXI data) will set the default to list data found at https://heasarc.gsfc.nasa.gov/FTP/maxi/data/. Note that data will be listed on 2010-01-03 (one day past the end of the request) in order to get all data that overlaps day boundaries. The total listing should come to 90 files in all, but they will not be downloaded. The code will also note any local files which match the request.

> Example 2:

  mxdownload_wget.pl --coordinates 55.5,15.0 --dates 2016-09-30,2016-10-10 --instruments all --localdir ~/MAXI --chatter 2 --auxilall
Get both instruments at both bit rates from MAXI for R.A. 55.5 Dec 15.0 between Sep 30 and Oct 10, 2016. Download the files into the local directory ~/MAXI, run in a slightly quieter mode, and get all the auxillary files, not just the standard set expected for the MAXI FTOOLS. Note that single dash - or double dash -- ("double dutch") formats for arguments are valid (but not special characters such as em-dash or en-dash), and paired arguments need to be seperated by ',' without any space.

SEE ALSO

LAST MODIFIED

Dec 2022