DESCRIPTION¶

The set of command-line tools that come with it (called the rytools) use a number of common conventions to specify colors, line styles, font sizes, and other configuration parameters.

The conventions used in the rytools differs slightly from those used when programming with Rayon in Python. For a detailed treatment of the latter, see Conventions Used in Rayon in the Rayon Reference Manual.

COMMAND INVOCATION¶

For a detailed description of rytool configuration, see ryrc.

All rytools support the following options.

--help

Flag. Print a brief tool description and synopsis of available options and exit.

--input-path <filename>

The name of a file to use as input. If filename is a hyphen (-), standard input will be used.

--output-path <filename>

Required. The name of a file to use as output. The type of file will be inferred from the file extension. Supported extensions (and file formats) are .pdf (Portable Document Format), .png (Portable Network Graphics), .svg (Scalable Vector Graphics), and .ps (PostScript).

--width <num>

The width of the image, as a number of pixels or points. (See SIZE AND DISTANCE.)

--height <num>

The height of the image, as a number of pixels or points. (See SIZE AND DISTANCE.)

COLUMN SPECIFICATION¶

Many command options require the specification of a column of data from the command’s input. Columns may be specified as a numeric index, where the leftmost column lexicographically in the input is column 0. If the input data has column names (see rydataformat), the names may be used to specify columns as well.

SIZE AND DISTANCE¶

Two different kinds of rytools conventions exist to specify size or distance. Some options simply take a number of points or pixels:

rytimeseries --annotation-label-spacing=4 ...

Other options take a size specification: a number followed by one of the suffixes “px” or “pt”, representing the number of pixels or points to use for the size/distance. The unit suffixes are interchangeable; the unit used will be the device unit of the output (generally pixels for raster output like PNG and points for vector output like PDF or SVG.)

SCALES¶

Many rytools can plot data apply different scales to data before visualization. In general, the following scales are available.

linear

Plot the data on a linear scale.

log

Plot the data on a log scale.

clog

Add the constant value 1 to the data, then plot on a log scale. This introduces some error to the scale (particularly for small non-integer values), but, unlike log, permits the input to contain zeroes.

TICK MARKS¶

Several rytools use tick mark specifications to express where tick marks should be placed. A tick mark specification is a comma-separated list of tick specifiers, which consist of a specifier type and and (optionally) a set of arguments to customize the time, again separated by commas, for example the following:

ryscatterplot ... --x-ticks at(1,2),min,gt(1000)

Would place ticks on the X axis at the values 1 and 2, the minimum value on the scale, and all points on the scale whose value is greater than 1000.

The possible position specifiers are:

at(pos,...)

Place a tick mark at each of the specified positions on the scale.

every(mod)

Place a tick mark at every position on the scale evenly divisible by mod. For example, on a scale running from 0-10, every(3) will place tick marks at 3, 6 and 9.

If mod is a time delta specification (see DATES AND TIMES) and the column contains datetime data, tick marks will be placed at time points divisible by that interval. For instance, on a scale running from 2001-01-01T01:23:45 to 2001-01-01T01:25:03, every(30s) will place tick marks at 01:24:00 and 01:24:30.

ge(num)

Place a tick mark for each data point whose value is greater than or equal to num.

gt(num)

Place a tick mark for each data point whose value is greater than num.

le(num)

Place a tick mark for each data point whose value is less than or equal to num.

lt(num)

Place a tick mark for each data point whose value is less than num.

max

Place a tick mark at the largest point in the data.

med

Place a tick mark at the median of the data.

min

Place a tick mark at the smallest point in the data.

n(num)

Place n automatically-selected “nice” tick marks on the scale. The tick selection algorithm will try to select exactly n tick marks, but may choose more or less if it cannot find n suitable tick marks.

none

Place no tick marks on the scale. (Use to override defaults.)

p(num)

Place a tick mark at the position marking the n th percentile of the data.

smax

Place a tick mark at the largest point on the scale.

smin

Place a tick mark at the smallest point on the scale.

MARKER SHAPE¶

The following marker shape styles are available:

arrow

Draw an v-shaped arrow head at the point

dot

Draw a filled dot at the point

circle

Draw an unfilled circle at the point

vline

Draw a vertical line at the point

hline

Draw a horizontal line at the point

cross

Draw a cross at the point

none

Draw nothing at the point

LINE STYLES¶

A number of line-drawing styles are available in the rytools. For options specifying line styles, the following values are valid:

• solid
• dotted
• dashed
• dotdash
• none

COLORS¶

For specifying colors, Rayon follows the format described in http://www.w3.org/TR/CSS2/syndata.html#color-units and http://www.w3.org/TR/css3-color, with three two exceptions:

• When specifying colors in hexadecimal notation, the leading octothorpe (#) character may be omitted.
• Alpha channels are supported in hexadecimal notation as well as in functional notation.
• The hsl(...) and hsl(...) specification forms are not supported.

For example, here are all the ways to specify a particular shade of blue to the rytools (text following a # character is a comment):

Method	Value
Name	blue
RGB	00f
RGBA	00ff
RRGGBB	0000ff
RRGGBBAA	0000ffff
RGB (functional)	rgb(0, 0, 255)
RGB (functional, percentage)	rgb(0%, 0%, 100%)
RGBA (functional)	rgb(0, 0, 255, 1.0)
RGBA (functional, percentage)	rgb(0%, 0%, 100%, 1.0)

DATES AND TIMES¶

To specify dates, times and relative time periods (“time deltas), use the ISO-8601 standard representation. http://www.w3.org/TR/NOTE-datetime describes this standard.

SEE ALSO¶

rytools(5)