Time series

This routine is a general purpose utility to list of selected data from FITS files, especially with calibration included. The most important instance of time-series are light curves.

Command


munipack timeserie [...] file(s)

Description

This utility is designed for listing of various quantities from a set of already processed frames to create of time-series. Both instrumental and calibrated data can be used. Full calibrated data including astrometry and photometry calibration are preferred.

By listing of a set of processed files, this tool creates a time dependence of a required quantity. The quantity is selected as a FITS-table column name and stored in a time series table. The time series of a light-like quantity is referenced as a light curve (LC).

The utility can be used to derive various kinds of times-like quantities.

Time

The time can be specified for reference points:

At Middle (--time-stamp=MID): The time specifies exactly at middle of exposure duration. Computed as begin time plus half of exposure. This is default.
At Begin (--time-stamp=BEGIN): The time specifies exactly at begin of exposure.
At End (--time-stamp=END): The time specifies exactly at end of exposure.

Following types of time can be specified (Julian day on wiki):

Julian date (-T JD): The time is specified in Julian dates in UT by default.
Modified Julian date (-T MJD): The time is specified in modified Julian dates (JD − 2400000.5) in UT.
Heliocentric Julian date (-T HJD): The time is specified in Julian dates at barycenter of solar system in UT.
Phase (-T PHASE): The time is specified as phase in UT. The phase φ is computed from a reference epoch e₀ given by --epoch in Julian days and period P given by --period in days: φ = {(t - e₀)/P} (where {.} operator provides fractional part (see Floor and ceiling functions).

See also detailed description at description of output table.

Prerequisites

Needs astrometry and photometry. To get calibrated fluxes or magnitudes, needs the photometry calibration.

Input And Output

On input, list of frames containing both astrometric and photometric information is expected.

On output, the FITS table representing the time series is created. All quantities can be also print on standard output.

This utility requires to identify both time and duration of exposures. By default, standard FITS keywords DATE-OBS and EXPTIME are used. They can be redefined with help of environment variables FITS_KEY_DATEOBS and FITS_KEY_EXPTIME.

There is also possibility to decode of times in legacy two-item format. In this case, date of form YY/MM/DD is included as FITS_KEY_DATEOBS while time HH:MM:SS is identified by keyword FITS_KEY_TIMEOBS which set to TIME-OBS by default.

Parameters

-c, --coo "α,δ ... ": Coordinates of all object(s) to list as twices separated by comma (like 25.3,0.6) or semicolon (like 25,3;0,6) as depends on your locale language convention. It is treated as a single program argument, more objects can be specified as twices separates by spaces (or | in doubts) and enclosed in aphostrophes or quotes (like "25.3,0.6 23.5,6.0").
-cat file: Coordinates of objects are given by the FITS file (see below). It is less convenient, but specification of proper motion is possible (it can be important for rapid flying rocks) as well as many objects.
-l, --col: Output label(s) to list (must exactly match names of column(s) in files on input).
-K, --keys: Values of the keywords(s) in FITS header to list. If any key is presented in more extensions, the first successful match is listed only.
-T, --time-type: JD − Julian date (default), MJD − modified JD, HJD − heliocentric JD, PHASE
--time-stamp: reference time point: mid (default), begin, end
--lc-epoch: reference time point of light curve elements in JD
--lc-period: period light curve elements in days
--coo-type: Specifies of type of coordinates as RECT (rectangular) or DEG (spherical) given by -c,--coo. The value is used for computation of distance during object searching.
--coo-col: column(s) of quantities used as coordinates. RAJ2000,DEJ2000 are used by default.
--tol: search radius for object identification in degrees
--extname: An identifier of FITS-extension, a first table extension is selected by default.
--stdout: results print also to standard output.
--enable-filename: results print contains also filenames
--enable-horizon: computes also horizontal coordinates: azimuth and zenith distance
--disable-timetype: disable print of time-type quantity

Note. Some parameters (-l, -col, -c, -coo, -coocol) has been changed during Spring 2018.

Stars Selection And Catalogue

By default, all stars on all frames are processed and stored to the output file. To select stars, there are two ways:

specify coordinates on the command-line
use a catalogue

For a few stars request, the simpler way is specification of coordinates on the command line. Use twices of equatorial coordinates (Right Ascension and Declination) in degrees separated by commas (or semicolon). For example:

$ munipack timeseries -c "330.689,42.2765 330.667,42.2860" file.fits

More general way is use of a table with coordinates. Important advantages over command line:

Very useful for passing of many stars and to use it repeatedly.
Proper motion can be specified. The file header can provide additional information (reference epoch) and units for all coordinates (complex info is crucial reason for use file).

The proper motion can be important for near and moving stars and should by used for flying rocks.

Catalogue For Stars Selection

Format of the catalogue is very restrictive and must be carefully followed. One is stored in FITS file with a just one table extension (EXTNAME doesn't matter). The header must contain keyword EPOCH which denotes the reference time t₀ in Julian days for object coordinates. The current positions at t are computed from reference coordinates α₀, δ₀ and proper motions μ_α0, μ_δ0 (in degrees per century) as:
α = α₀ + μ_α0 /(t - t₀) / T
δ = δ₀ + μ_δ0 /(t - t₀) / T
where T is the time unit given by TUNITS keywords in header. One is one for deg/day and 365.25 for arcsec/year.

The most simple way how to create the catalogue, timeserie_cat.lst can be directly used as example and edited. The FITS file timeserie_cat.fits is created as

$ munipack fits --restore timeserie_cat.lst

Table structure
Column	Description	Units
RAJ2000	Right ascension α₀	degrees
DEJ2000	Declination δ₀	degrees
pmRA	proper motion in RA μ_α0	arcsec/year or deg/day^[†]
pmDE	proper motion in DE μ_δ0	arcsec/year or deg/day^[†]

^[†] The only string 'arcsec/year' or 'deg/day' must be present and specified exactly via TUNIT3 and TUNIT3 keywords. Setting of proper motions to zeros will usually satisfactory (except really fast moving objects like Barnard star or asteroids).

Caveats

This utility is primary indented and designed for working with low amount of data. The typical usage is listing of light curves or positions of motion of objects during a night. Another example can be study of any instrumental quantity. This routine is generic analysing tool.

Use on large archives of observations is not recommended. Spidering over a complicated directory structure would be really slow. To work with a large data archive, use Munipack to create tables with photometry and astrometry data and keep the results in a database. Much more better idea should be to import the data into some Virtual Observatory engine. Popular VO-engines are VO-Dance, Saada or GAVO DaCHS.

Examples

Light curve in magnitudes for stars at given coordinates listing all R-filter (by filename) files:


$ munipack timeseries -c "47.0422,40.9560 46.2941,38.8403" -l MAG,MAGERR 0716_*R.fits

Historical note

Timeseries has been designed by format SimpleTimeseries (dead link) due J. Bloom which is abandoned now. Therefore the format of data is adapted for Munipack purposes and it should be changed in future.