Next Previous Up Contents
Next: Usage
Up: Command Reference
Previous: Examples

## B.19 `plot2time`: Draws a time plot

`plot2time` draws plots where the horizontal axis represents time. The time axis can be labelled in various different ways including MJD, decimal year and ISO-8601 form.

Positional coordinates are specified as `t`, `y` pairs, with an optional `ttype` specifier to indicate how the input value is to be interpreted, e.g.:

       plot2time in1=series.fits layer1=line t1=EPOCH ttype1=MJD y1=ENERGY

Time values can be represented in various ways in input data, for instance as Julian Day, Modified Julian Date, decimal years since 0AD, Unix seconds, ISO-8601, or variants of some of the above with additional offsets. In some cases the input format contains enough metadata to determine how the values should be mapped to a common timescale (so for instance they can be plotted as MJD or Year/Month/Day), and in other cases they do not. For example CDF files and VOTable 1.4 files with `TIMESYS` markup contain sufficient metadata, and text inputs using the ISO-8601 format can usually be identified and understood, but there's no way to tell automatically whether a numeric column in a CSV file represents MJD, seconds since a known epoch, decimal years, or anything else. For this reason the `ttypeN` parameter is provided for all the layer types with a `tN` coordinate, as follows:

`ttypeN = DecYear|MJD|JD|Unix|Iso8601` (TimeMapper)
  Selects the form in which the Time value for parameter `tN` is supplied. Options are:
  - `DecYear`: Years since 0 AD
  - `MJD`: Modified Julian Date
  - `JD`: Julian Day
  - `Unix`: Seconds since midnight 1 Jan 1970
  - `Iso8601`: ISO 8601 string
  If left blank, a guess will be taken depending on the data type of the value supplied for the `tN` value.

This command, unlike the other `plot2*` commands at time of writing, can be used to draw multi-zone plots. These are plots with different panels stacked vertically so that different datasets can share the same horizontal (time) axis, but have separate vertical axes, colour maps, legends etc. The horizontal axes are always synchronized between zones. This is currently controlled with the `zoneN` parameter. For any layer with a layer suffix `N`, you can specify a zone identifier as an arbitrary string, `Z`, by supplying the parameter `zoneN=Z`. Layers with the same value of `zoneN` are plotted in the same zone, and layers with different values are plotted in different zones. If no `zoneN` is given, the layer is assigned to a single (unnamed) zone, so with no zone parameters specified all plots appear in a single zone. Parameters specific to a given zone can then be suffixed with the same `Z` zone identifier. The examples section illustrates what this looks like in practice.

Note: The multi-zone feature is experimental. As currently implemented it lacks some features. The interface may be changed in a future version.

Content is added to the plot by specifying one or more plot layers using the `layerN` parameter. The `N` part is a suffix applied to all the parameters affecting a given layer; any suffix (including the empty string) may be used. Available layers for this plot type are: `line`, `linearfit`, `mark`, `fill`, `quantile`, `grid`, `histogram`, `kde`, `knn`, `densogram`, `gaussian`, `yerror`, `spectrogram`, `label`, `function`.

- B.19.1 Usage
- B.19.2 Examples

Next Previous Up Contents
Next: Usage
Up: Command Reference
Previous: Examples

STILTS - Starlink Tables Infrastructure Library Tool Set
Starlink User Note256
STILTS web page: http://www.starlink.ac.uk/stilts/
Author email: m.b.taylor@bristol.ac.uk
Mailing list: topcat-user@jiscmail.ac.uk