Permalink
457c288 Sep 2, 2016
@rashidkpc @moshe
329 lines (249 sloc) 15.4 KB

Timelion function reference

This document is auto generated from the timelion code. Do not submit pulls against this document. You want to submit a pull against something in the series_functions/ directory.

Data sources

Data sources can start a chain, they don't need to be attached to anything, but they still need to start with a . (dot). Data retreived from a data source can be passed into the chainable functions in the next section.

.graphite()

Pull data from graphite. Configure your graphite server in timelion.json

Argument Accepts Description
metric string Graphite metric to pull, eg _test-data.users.*.data
offset string Offset the series retrieval by a date expression. Eg -1M to make events from one month ago appear as if they are happening now
fit string Algorithm to use for fitting series to the target time span and interval. Available: average, carry, nearest, none, scale,

.quandl()

Pull data from quandl.com using the quandl code. Stick your free API key in timelion.json. API is rate limited without a key

Argument Accepts Description
code string The quandl code to plot. You can find these on quandl.com.
position number Some quandl sources return multiple series, which one should I use? 1 based index.
offset string Offset the series retrieval by a date expression. Eg -1M to make events from one month ago appear as if they are happening now
fit string Algorithm to use for fitting series to the target time span and interval. Available: average, carry, nearest, none, scale,

.static()

Draws a single value across the chart

Argument Accepts Description
value number/string The single value to to display, you can also pass several values and I will interpolate them evenly across your time range.
label string A quick way to set the label for the series. You could also use the .label() function
offset string Offset the series retrieval by a date expression. Eg -1M to make events from one month ago appear as if they are happening now
fit string Algorithm to use for fitting series to the target time span and interval. Available: average, carry, nearest, none, scale,

.worldbank_indicators()

Pull data from http://data.worldbank.org/ using the country name and indicator. The worldbank provides mostly yearly data, and often has no data for the current year. Try offset=-1y if you get no data for recent time ranges.

Argument Accepts Description
country string Worldbank country identifier. Usually the country's 2 letter code
indicator string The indicator code to use. You'll have to look this up on data.worldbank.org. Often pretty obtuse. Eg SP.POP.TOTL is population
offset string Offset the series retrieval by a date expression. Eg -1M to make events from one month ago appear as if they are happening now
fit string Algorithm to use for fitting series to the target time span and interval. Available: average, carry, nearest, none, scale,

.worldbank()

Pull data from http://data.worldbank.org/ using path to series. The worldbank provides mostly yearly data, and often has no data for the current year. Try offset=-1y if you get no data for recent time ranges.

Argument Accepts Description
code string Worldbank API path. This is usually everything after the domain, before the querystring. Eg: /en/countries/ind;chn/indicators/DPANUSSPF.
offset string Offset the series retrieval by a date expression. Eg -1M to make events from one month ago appear as if they are happening now
fit string Algorithm to use for fitting series to the target time span and interval. Available: average, carry, nearest, none, scale,

.es()

Pull data from an elasticsearch instance

Argument Accepts Description
q string Query in lucene query string syntax
metric string An elasticsearch single value metric agg, eg avg, sum, min, max or cardinality, followed by a field. Eg "sum:bytes", or just "count"
split string An elasticsearch field to split the series on and a limit. Eg, "hostname:10" to get the top 10 hostnames
index string Index to query, wildcards accepted
timefield string Field of type "date" to use for x-axis
kibana boolean Respect filters on Kibana dashboards. Only has an effect when using on Kibana dashboards
interval string DO NOT USE THIS. Its fun for debugging fit functions, but you really should use the interval picker
offset string Offset the series retrieval by a date expression. Eg -1M to make events from one month ago appear as if they are happening now
fit string Algorithm to use for fitting series to the target time span and interval. Available: average, carry, nearest, none, scale,

Chainable functions

Chainable functions can not start a chain. Somewhere before them must be a data source function. Chainable functions modify the data output directly from a data source, or from another chainable function that has a data source somewhere before it.

.abs()

Return the absolute value of each value in the series list

This function does not accept any arguments.

.bars()

Show the seriesList as bars

Argument Accepts Description
width number Width of bars in pixels
stack boolean Should bars be stacked, true by default

.color()

Change the color of the series

Argument Accepts Description
color string Color of series, as hex, eg #c6c6c6 is a lovely light grey. If you specify multiple colors, and have multiple series, you will get a gradient, eg "#00B1CC:#00FF94:#FF3A39:#CC1A6F"

.condition()

Compares each point to a number, or the same point in another series using an operator, then sets its valueto the result if the condition proves true, with an optional else.

Argument Accepts Description
operator string Operator to use for comparison, valid operators are eq (equal), ne (not equal), lt (less than), lte (less than equal), gt (greater than), gte (greater than equal)
if number/seriesList The value to which the point will be compared. If you pass a seriesList here the first series will be used
then number/seriesList The value the point will be set to if the comparison is true. If you pass a seriesList here the first series will be used
else number/seriesList The value the point will be set to if the comparison is false. If you pass a seriesList here the first series will be used

.cusum()

Return the cumulative sum of a series, starting at a base.

Argument Accepts Description
base number Number to start at. Basically just adds this to the beginning of the series

.derivative()

Plot the change in values over time.

This function does not accept any arguments.

.divide()

Divides the values of one or more series in a seriesList to each position, in each series, of the input seriesList

Argument Accepts Description
divisor seriesList/number Number or series to divide by. If passing a seriesList it must contain exactly 1 series.

.first()

This is an internal function that simply returns the input seriesList. Don't use this

This function does not accept any arguments.

.fit()

Fills null values using a defined fit function

Argument Accepts Description
mode string The algorithm to use for fitting the series to the target. One of: average, carry, nearest, none, scale,

.hide()

Hide the series by default

Argument Accepts Description
hide boolean Hide or unhide the series

.label()

Change the label of the series. Use %s reference the existing label

Argument Accepts Description
label string Legend value for series. You can use $1, $2, etc, in the string to match up with the regex capture groups
regex string A regex with capture group support

.legend()

Set the position and style of the legend on the plot

Argument Accepts Description
position string/boolean Corner to place the legend in: nw, ne, se, or sw. You can also pass false to disable the legend
columns number Number of columns to divide the legend into

.lines()

Show the seriesList as lines

Argument Accepts Description
width number Line thickness
fill number Number between 0 and 10. Use for making area charts
stack boolean Stack lines, often misleading. At least use some fill if you use this.
show number/boolean Show or hide lines
steps number/boolean Show line as step, eg, do not interpolate between points

.log()

Return the logarithm value of each value in the series list (default base: 10)

Argument Accepts Description
base number Set logarithmic base, 10 by default

.max()

Maximum values of one or more series in a seriesList to each position, in each series, of the input seriesList

Argument Accepts Description
value seriesList/number Sets the point to whichever is higher, the existing value, or the one passed. If passing a seriesList it must contain exactly 1 series.

.min()

Minimum values of one or more series in a seriesList to each position, in each series, of the input seriesList

Argument Accepts Description
value seriesList/number Sets the point to whichever is lower, the existing value, or the one passed. If passing a seriesList it must contain exactly 1 series.

.movingaverage()

Calculate the moving average over a given window. Nice for smoothing noisey series

Argument Accepts Description
window number Number of points to average over
position string Position of the averaged points relative to the result time. Options are left, right, and center (default).

.movingstd()

Calculate the moving standard deviation over a given window. Uses naive two-pass algorithm. Rounding errors may become more noticeable with very long series, or series with very large numbers.

Argument Accepts Description
window number Number of points to compute the standard deviation over

.multiply()

Multiply the values of one or more series in a seriesList to each position, in each series, of the input seriesList

Argument Accepts Description
multiplier seriesList/number Number or series by which to multiply. If passing a seriesList it must contain exactly 1 series.

.points()

Show the series as points

Argument Accepts Description
radius number Size of points
weight number Thickness of line around point
fill number Number between 0 and 10 representing opacity of fill
fillColor string Color with which to fill point
symbol string cross, circle, triangle, square or diamond
show boolean Show points or not

.precision()

number of digits to round the decimal portion of the value to

Argument Accepts Description
precision number Number of digits to round each value to

.props()

Use at your own risk, sets arbitrary properties on the series. For example .props(label=bears!)

Argument Accepts Description
global boolean Set props on the seriesList vs on each series

.range()

Changes the max and min of a series while keeping the same shape

Argument Accepts Description
min number New minimum value
max number New maximum value

.scale_interval()

Changes scales a value (usually a sum or a count) to a new interval. For example, as a per-second rate

Argument Accepts Description
interval string The new interval in date math notation, eg 1s for 1 second. 1m, 5m, 1M, 1w, 1y, etc.

.subtract()

Subtract the values of one or more series in a seriesList to each position, in each series, of the input seriesList

Argument Accepts Description
term seriesList/number Number or series to subtract from input. If passing a seriesList it must contain exactly 1 series.

.sum()

Adds the values of one or more series in a seriesList to each position, in each series, of the input seriesList

Argument Accepts Description
term seriesList/number Number or series to sum with the input series. If passing a seriesList it must contain exactly 1 series.

.title()

Adds a title to the top of the plot. If called on more than 1 seriesList the last call will be used.

Argument Accepts Description
title string Title for the plot.

.trim()

Set N buckets at the start or end of a series to null to fit the "partial bucket issue"

Argument Accepts Description
start number Buckets to trim from the beginning of the series. Default: 1
end number Buckets to trim from the end of the series. Default: 1

.yaxis()

Configures a variety of y-axis options, the most important likely being the ability to add an Nth (eg 2nd) y-axis

Argument Accepts Description
yaxis number The numbered y-axis to plot this series on, eg .yaxis(2) for a 2nd y-axis.
min number Min value
max number Max value
position string left or right
label string Label for axis
color string Color of axis label

.holt()

Sample the beginning of a series and use it to forecast what should happen
via several optional parameters. In general, like everything, this is crappy at predicting the
future. You're much better off using it to predict what should be happening right now, for the
purpose of anomaly detection. Note that nulls will be filled with forecasted values. Deal with it.
Argument Accepts Description
alpha number
    Smoothing weight from 0 to 1.
    Increasing alpha will make the new series more closely follow the original.
    Lowering it will make the series smoother  

beta | number | Trending weight from 0 to 1. Increasing beta will make rising/falling lines continue to rise/fall longer. Lowering it will make the function learn the new trend faster
gamma | number | Seasonal weight from 0 to 1. Does your data look like a wave? Increasing this will give recent seasons more importance, thus changing the wave form faster. Lowering it will reduce the importance of new seasons, making history more important.

season | string | How long is the season, eg, 1w if you pattern repeats weekly. (Only useful with gamma)
sample | number | The number of seasons to sample before starting to "predict" in a seasonal series. (Only useful with gamma, Default: all)

.trend()

Draws a trend line using a specified regression algorithm

Argument Accepts Description
mode string The algorithm to use for generating the trend line. One of: linear, log
start number Where to start calculating from the beginning or end. For example -10 would start calculating 10 points from the end, +15 would start 15 points from the beginning. Default: 0
end number Where to stop calculating from the beginning or end. For example -10 would stop calculating 10 points from the end, +15 would stop 15 points from the beginning. Default: 0