Barth
Netterfield

    netterfield@astro.utoronto.ca

# Command Line Usage and Examples

A typical use of kst is from the command line to make X-Y plots or Z images from data files. kst can read ascii data, readdata/dirfile compatible binary files, and optionally (with external libraries) FITS images, PIOLib files, netCDF files, and HEALPix FITS files.

&kst; Command Line Synopsis

## kst

A plotting and data viewing program

The options are:

    kst
    Qt-options
    KDE-options
    options
    file

### Options

`[file...]`

  A .kst file, or one or more data files. Supported formats are ASCII columns, BOOMERANG frame files, BLAST dirfile files, and other optionally supported types. A .kst files stores all options that can be set by other flags. The following flags can be used to override the options set in the .kst file: `-F datafile`, `-n NS`, `-s NS`, `-f F0`, `-a`. The rest can not be overridden. If an override flag is given, it is applied to all vectors in the plot.

  ASCII data from stdin can be plotted by including "stdin" in the list `[file...]`.

`-y Y`

  The source for the Y axis data. For ASCII files, this is the column. For binary files, this is the field name. To plot multiple curves, this may be specified multiple times. The same source file, sample ranges, and X axis data are assumed.

`-e E`

  Error bars for Y axis data. For ASCII file, refer to the column holding the data. For binary files use the field name. If multiple `-y Y` options are given, this may also be used multiple times. Individual Y entries are associated in order with multiple E entries.

`-x X`

  The source for the X axis data. For ASCII files, this is the column. For readata files, this is the field name. If this option is not specified, the row number in the file is used. This option can only be given once.

`-z Z`

  The source for the Z matrix data (which gets displayed as an image). For ASCII files, this is the column containing the z data. For other optional formats (HEALPix, FITS image, etc), this is the name of the desired matrix field, as displayed in the matrix dialog. Some matrix-compatible datasources also allow using an alias which is the number of the desired matrix field. To plot multiple matrices, this may be specified multiple times.

`-p P`

  The source for power spectra. For ASCII files, this is the column. For binary files, this is the field name. To plot power spectra of multiple curves, this may be specified multiple times. The same source file, sample ranges and fft lengths are used for all Power Spectra requested from the command line.

`-l P`

  The length of the FFT used in power specra estimation is 2^P.

`-h H`

  The source for histograms. For ASCII files, this is the column. For binary files, this is the field name. Multiple histograms can be defined from the command line.

`-m NC`

  Used when multiple curves have been defined. Rather than plotting all curves in the same plot, plot each in its own plot,

`-f F0`

  The starting frame number (for readdata files) or row (for ASCII files) to read.

`-n`

  The number of frames (for readdata files) or rows (for ASCII files) to read.

`-s NS`

  The number of frames or rows to skip each read. This is useful when working with very large data files, to speed up response and conserve memory, in the case that the data are slowly varying.

`-a`

  Used in with the `-s NS`: rather than skipping each NS frames, average them. This provides a combination of very basic high pass filtering, and memory conservation.

`-F Datafile`

  Override the file to read the data from for all vectors listed in the .kst file. Can only be used in conjunction with a kst file.

`--print psfile`

  Rather than displaying the plot, export the image to a postscript file and exit. *BUG note: even though no windows are opened on screen, access to the X server is still required.*

`--png pngfile`

  Rather than displaying the plot, export the image to a png file of dimensions 640x480 and exit. *BUG note: even though no windows are opened on screen, access to the X server is still required.*

### Command Line Examples

Several examples of typical use follow.

To plot column 1 a file (tmp.dat) of ASCII data:

    kst -y 1
    tmp.dat

To plot column 2, 3, and 4 vs. column 1 of an ASCII file, in 1 plot:

    kst -x 1 -y 2 -y 3 -y 4 tmp.dat

To plot column 2, 3, and 4 vs. column 1 of an ASCII file, in 3 plots, arranged in 1 column:

    kst -x 1 -y 2 -y 3 -y 4 -m 1 tmp.dat

To plot 500 rows of column 2 of an ASCII file, starting at line 100:

    kst -y 2 -f 100 -n 500 tmp.dat

To plot the first 100,000 rows of column 2 of an ASCII file, averaging every 100 rows:

    kst -y 2 -f 0 -n 100000 -s 100 -a tmp.dat

(Using optional HEALPix Data Source) To plot the first 3 maps in a HEALPix FITS file in a 2x2 grid:

    kst -z 1 -z 2 -z 3 -m 2 healpix_example_sm.fits

(Using optional HEALPix Data Source) To plot a map with a specific field name in a HEALPix FITS file:

    kst -z "1 - TEMPERATURE (Kelvin)" healpix_example_sm.fits