Easy Timeline Syntax

c allskip 6023-6025 7123 8888 9999
! the beginning:
#yup this is it
comment another comment

timeline MH1X efficiency
file mh1xeff
category muon
hist imu: efficiency all planes
val v1
err e1
skip 9785-9791 9305
start 8192

timeline MH efficiency
file mh_all_eff
category muon
hist imu: efficiency all planes
val v1..4/4
err e1..4
# equivalent to: err sqrt(e1**2 + e2**2 + e3**2 + e4**2)

General Format

• Lines are either blank (ignored), or contain a keyword followed by data.
• The keyword is case-insensitive.
• If the first word is c or comment, or if a line begins with a ! or #, it is ignored.

Keywords

Global Keywords:

allskip

Run numbers for alltimelines to skip. This should be used sparingly, or not at all. Whole ranges of run numbers can be given. for example, 9785-9791 indicated all run numbers between and including 9785 and 9791. Run numbers or ranges are separated by commas or whitespace. If more than one allskip keyword is given, the additional run numbers are added to the list.

Timeline Keywords:

timeline

Begins defining a timeline. The "data" is the name of the timeline.

category

Timelines can be grouped into categories. If no category is given, it defaults to "none". (The timelines are placed in subdirectories which are the name with a ".dir" extension.

hist

The title of the histogram. This title is case-insensitive (converted to upper case automatically). If the title is "none", then the timeline does not require any histogram data. This only works if the value and error are computed from variables and/or scaler rates alone. (See Quantities below)

file

The filename containing the timeline data. ".tl" is automatically appended. If no filename is given, the timeline name is used instead, with goofy characters converted to underscores.

val

The value to be plotted. See "quantities" below. This must be specified for each timeline. Well, if it is omitted, it is assumed to be "v1".

err

The uncertainty of the value. If omitted, no error is reported.

skip

The run numbers for this timeline to ignore. Ranges can be given like in allskip.

start

Indicates which run number to begin accumulating data for. Defaults to zero. If an oddpack file does not contain the histogram specified, it will be ignored. So, indicating a start number is not necessary, but can speed up the timeline accumulation if you're not interested in earlier data or you know that a histogram was recently added.

Variable Keywords:

variable

Begins defining a variable. The data is the name of the variable. It IS case-sensitive, and can only contain letters and numbers.

hist

The histogram title containing the data needed for the variable.

val

A quantity (see below) defining the value of the variable.

Quantities

The following special syntax is included:

• v1, v2, v67 are examples of bin contents. v1 is the value of the first bin in the histogram.
• e1, e2, e67 represent the equivalent error bars for those "histograms" which are have them (weighted histograms and PLTs).
• If a bin is referred to which does not exist, its value is unpredictable. If an error value is referred to for a normal histogram, its value is unpredictable.
• vu, vo, eu, and eo represent the underflow and overflow bins.
• v1..3 is an example of an automatic sum. It is equivalent to (v1 + v2 + v3).
• e5..7 = sqrt(e5**2 + e6**2 + e7**2)
• v@6.7 is an way to find the bin height corresponding to an X-value of 6.7. Numbers can be written in practically any format, including "5", and "-.09e+8".
• v@7.8..11.1 is an example of adding over a specified range. Its a combination of the v@6.7 syntax and v4..7 syntax.
• e@4.2 and e@6..8.2 also work the way they should. Adding over a range is performed in quadrature, as is e1..3 .
• $name refers to the variable "name", defined with the variable command mentioned above. Again, variable names are case-sensitive, and can consist only of letters and numbers.

Functions for timeline quantities

• Special custom functions (feel free to ask for more)

  SumAll()

  returns the total bin heights for all the bins plus the underflow and overflow bins.

  Average()

  finds the average of the histogrammed distribution. Its the mean of all the bin centers, weighted by their contents. Underflow and overflow are not included. If it would be useful, I could allow two optional arguments indicating a range to average over.

  Threshold(thr, start)

  Finds the x-value where the plot crosses the threshold thr (linearly interpolating between points. start is the bin number to start searching from. The data points are visited from left to right. If you leave out the second argument, start defaults to 0 so even the first bin could cross the threshold.

  LastBinHeight()

  returns the bin height of the last bin. If it would be useful, I could make more general functions binval(n) and binerr(n). n could be a computed value, and if it were negative it would refer to bins over from the right side (-1 being the last bin).

• Some possibly useful built-in (Perl) functions
  abs(x)
  The absolute value of x.
  sin(x), cos(x), exp(x), log(x)
  exactly what you would expect.
  int(x)
  The integer part function.
  rand(x)
  a random fractional number between 0 and x. (I can't think of any reason to use this one right now).

Scaler Values

The values are reffered to with the syntax:

• total spills
• live spills
• spill length
• live time
• The name of a scaler followed by

  cnts

  Counts

  cpsp

  Counts per spill

  cpsm

  Counts per sem

  cplt

  Counts per sem per livetime

Processing

Ideas for Future Enhancement

• Some kind of shorthand notation for calculating yields.
• Make variables and/or timelines whose values and histogram titles depend on the run number.