Munipack's logo

Time Series

This routine is general purpose utility to list of selected elements from calibrated files.

Command

munipack timeserie [...] file(s)

Description

This utility is designed for listing of time series of a various quantities from a set of already processed frames. 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.

Prerequisites

Needs astrometry and photometry. To get calibrated fluxes or magnitudes, needs 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.

Parameters

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 e0 given by --epoch in Julian days and period P given by --period in days: φ = {(t - e0)/P} (where {.} operator provides fractional part (see Floor and ceiling functions).
See also detailed description at description of output table.

Listing:

-c, --column
column(s) to output list (must exactly match names of column(s) in images on input)
-C, --coocolumn
column(s) of quantities used as coordinates
-x, --extname
An identifier of FITS-extension
-T, --time-type
JD − Julian date (default), MJD − modified JD, HJD − heliocentric JD, PHASE, AIRMASS
--time-stamp
reference time point: mid (default), begin, end
--diffmag
differential magnitudes (with respect to a first object)
--epoch
reference time point of light curve elements in JD
--period
period light curve elements in days
--tol
search radius for object identification in degrees
--stdout
results print also to standard output
--cat
catalogue of coordinates from the FITS file

When -c or -C are not specified, the structure of the first file is discovered. The coordinates are recognised automatically as rectangular (equivalent to -C X,Y) or spherical (-C RA,DEC). All other columns (except coordinates) are listed by default (usually as -c COUNT,COUNTERR, -c PHOTON,PHOTONERR, -c MAG,MARERR, etc.).

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:

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 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:

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 t0 in Julian days for object coordinates. The current positions at t are computed from reference coordinates α0, δ0 and proper motions μα0, μδ0 (in degrees per century) as:
  α = α0 + μα0 /(t - t0) / T
  δ = δ0 + μδ0 /(t - t0) / 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
ColumnDescriptionUnits
RAJ2000Right ascension α0degrees
DEJ2000Declination δ0degrees
pmRA proper motion in RA μα0arcsec/year or deg/day[†]
pmDECproper motion in DEC μδ0arcsec/year or deg/day[†]
[†] The 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).

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

Timeseries for all stars:

$ munipack timeseries M67_Blue.fits

Light curve for stars at coordinates:

$ munipack timeseries 256,156 258,88 0716_*R.fits

See Also

Data format for timeseries, Light Curve Tutorial, Common options.