pdx Configuration | Index | pdx Interactive Mode |
{int}, {double} | signed numbers |
5, 3.14 |
{string} | character strings |
"Hugo" |
{time} | mostly a time duration, seldomly
really a time |
09:13 |
{timestamp} | a concrete point in history containing date and time | 2009-12-31-7:30:01 |
{selection} | an amount of timestamp-value-pairs | |
{color} | a color in hexadecimal RGB
notation |
#00FF00 |
{nothing} | for function results only:
the result of the function is empty and can't be used for
further calculations |
Time spans |
|
---|---|
The
following functions calculate each a concrete time span. A
possible {int}
argument is just a factor. If there's no {int} argument this
factor is 1. The plural forms don't have a special meaning.
They're just a more intuitive notation. |
|
(second)
→ {time} (second {int}) → {time} (seconds {int}) → {time} (minute) → {time} (minute {int}) → {time} (minutes {int}) → {time} (hour) → {time} (hour {int}) → {time} (hours {int}) → {time} (day) → {time} (day {int}) → {time} (days {int}) → {time} (week) → {time} (week {int}) → {time} (weeks {int}) → {time} |
The names of
these functions are self-explaning. |
(month)
→ {time} (month {int}) → {time} (months {int}) → {time} |
Note, a month is here always 30 days. The
specifications (month)
and (days 30)
are synonymous. |
(year)
→ {time} (year {int}) → {time} (years {int}) → {time} |
Note, a year is here always 365 days. The specifications (year) and (days 365) are synonymous. |
now |
|
---|---|
(now) → {timestamp} | The function now calculates an
actual timestamp. |
Note: if you use the command line option -f the returned
value is the time of the start of the application even if
this lies now some seconds back. So all calls to now return the same
timestamp if you use -f. |
midnight |
|
---|---|
(midnight) → {timestamp} | The function midnight calculates
a timestamp according to the following formula: tmidnight = tnow
+ 1 day - daytime + m
(m is the parameter midnight defined
in the file .pdrxrc)
The function gets the timestamp following immediately after the actual day, this means the actual day is included completely even if it's still running. Normally this timestamp is more handy than now to create reports and diagrams: now gets a still running, midnight a whole day. |
Note: The value of (midnight) depends
on the commandline parameter
-n. Example: Asume the actual time is 2011-07-08 17:07:38 and the parameter midnight is defined in .pdrxrc as 2:00 then (midnight) will calculate the timestamp 2011-07-09 02:00:00. |
Selection |
|
---|---|
The five implementations of the select function get data
values from a collection
and put the into a selection. A selection is a time limited, not by any manner of means
gapless part of a collection.
The mandatory {string} parameter names the collection. If the
collection is
empty or if not data value can be found according to the
time limitations the result selection is empty. |
|
(select {string})
→ {selection}
|
The function gets all data values of
the collection. |
(select {string} {timestamp}) → {selection} | The function gets the one data value from the collection who matches
the specified {timestamp}. |
(select {string} {timestamp} {timestamp}) → {selection} | The function gets all data values from the collection according to
the time span between the two {timestamp} parameters. |
(select {string} {time}) → {selection} | The function gets all data values from the collection according to
the time span between (now)-{time}
and (now). |
(select {string} {time} {timestamp}) → {selection} | The function gets all data values from the collection according to the time span between {timestamp}-{time} and {timestamp}. |
Examples: (select "*") get all data of the default collection
(select "*" 2009-12-01-12:34) get data of the default collection
since Dec 01 2009 12:34
(select "n" 2009-01-01-0:00 2010-01-01-0:00) get all data of the collection n of the year
2009
(select "l" (weeks 2)) get all data of the collection l of the last two
weeks
(select "l" (months 3) 2009-06-01-0:00) get all data of the collection l of the last
three months before June 01 2009
|
merge |
|
---|---|
The function merge allows the merge of selections, this means of values comming originally from different collections. This is useful for categorized values stored in several collections but belonging together anyway. | |
(merge keyword ...) → {selection} | keyword names the
function being used if two values from different collections collide by
having the same timestamp. keyword can be as follows:
|
Example: (merge avg (select "*" (days 7)) (select "x" (days 5))) |
fold |
|
---|---|
The function fold allows "folding" the time axis of a selection. Imagine a collection written on a paper strip and fold it in your mind so that periods of time lay above each other. With this technique you can compare days or months based on the data of several days and months. | |
(fold keyword1 keyword2 {selection}) → {selection} | keyword1
controls the folding interval. Instead of keyword1
the following specifications can be used: year, month, day, hour or minute. For
example, if you use day
the timestamps of the collection
will be cut til their day component, this means only the
time component remains. All values will then get timestamps
containing only 24 hours. keyword2 has the same meaing like keyword in the merge function. You can use here: avg, min, max, sum, first, last. |
Note: even the selection in the result of a folding operation must have valid timestamps. But there's no possibility to get an absolute timestamp after folding a period of time, several timestamps lay above each other. That's why these timestamps get the year 9999. According to the interval used also other parts of these timestamps (month, day and so on) are surely valid in their syntax but do not make sense. | |
Example: selection a (fold day avg (select "a")) (fold day first (select "a")) (fold day last (select "a")) -------------------- --------------------------- ----------------------------- ---------------------------- 2009-12-01 13:01 5.2 9999-01-01 13:01 5.45 <- avg! 9999-01-01 13:01 5.2 <- first! 9999-12-05 13:01 5.7 <- last! 2009-12-02 13:02 5.7 9999-01-01 13:02 5.7 9999-01-01 13:02 5.7 9999-01-01 13:02 5.7 2009-12-03 13:03 3.2 9999-01-01 13:03 3.2 9999-01-01 13:03 3.2 9999-01-01 13:03 3.2 2009-12-04 13:04 4.8 9999-01-01 13:04 4.8 9999-01-01 13:04 4.8 9999-01-01 13:04 4.8 2009-12-05 13:01 5.7 2009-12-06 13:06 5.3 9999-01-01 13:06 5.3 9999-01-01 13:06 5.3 9999-01-01 13:06 5.3 |
Statistik |
|
---|---|
The
statistic functions execute typical statistic calculations
upon a selection.
The functions calculate:
|
|
(func {selection}) → {selection} | execute the calculation based on the
whole selection,
the result contains a single row |
(func {selection} {time} {time}) → {selection} | execute the calculation based on the whole selection but take only values between the two day times, the result contains a single row |
The
following implementations use a keyword to name the aggregation
interval. This keyword
can be: year,
month, day, hour, minute, second. The result
has one row per interval. For instance, if you use day as aggregation
interval the result will contain one row per day of the
original selection. |
|
(func {selection} keyword) → {selection} | execute the calculation based on the whole selection, aggregate
according to keyword |
(func {selection} keyword {time} {time}) → {selection} | execute the calculation based on the whole selection, aggregate
according to keyword,
use only values between the two times |
The
functions avg
and sdv have a
sixth, floating
implementation. This one uses previous and following values
and leads to very nice curves. |
|
(func {selection} {int} {int}) → {selection} | execute the calculation based on the whole selection, use per
concrete value {int}
previous and {int}
following values and calculate in this floating window only,
this leads to ay many values in the result as values in the
original selection |
Examples: (avg (select "*")) compute the average over all
values of the default
collection
(sum (select "n" 3:30 9:00) day) get the daily sum of values
of the collection
n, sum only
values between 3:30 and 9:00
(avg (select "l" (month)) 5 5) get the floating average
over 11 values of the
collection l
for the last month
(first (select "*" (month)) day 4:00 9:00) get the first line of each
day of the last month from the default collection, take only values
between 4 and 9 o'clock
(last (select "*" (day)) hour) get the last line of each
hour of the last day from the default collection
|
|
Comparison |
|
---|---|
(==
{selection} {double}) → {selection} (!= {selection} {double}) → {selection} (< {selection} {double}) → {selection} (> {selection} {double}) → {selection} (<= {selection} {double}) → {selection} (>= {selection} {double}) → {selection} |
All these
functions compare each value of a selection with a specified constant. The
result will contain only those values who match the
comparison. So the selection
in the function result is as big as the original selection or lesser. |
Examples: (< (select "*") 5.0) get all values from the default collection
being less than 5.0
(>= (select "*") 7.0) get all values from the default collection
being greater than or equal 7.0
|
Arithmetics |
|
---|---|
(+
{double} {double})
→ {selection} (- {double} {double}) → {selection} (* {double} {double}) → {selection} (/ {double} {double}) → {selection} |
These four functions calculate with two simple numbers. However, the result is a selection to make it simpler to use it for further calculations. But this selection has only one row and on this row no timestamp. |
(+ {selection}
{double}) → {selection} (- {selection} {double}) → {selection} (* {selection} {double}) → {selection} (/ {selection} {double}) → {selection} |
This group of functions combines each value of the selection with a number. The result has as many rows as the specified selection. |
(+ {selection}
{selection}) → {selection} (- {selection} {selection}) → {selection} (* {selection} {selection}) → {selection} (/ {selection} {selection}) → {selection} |
These four functions handle two selections. During this
the timestamps of the selections
will be compared row by row and then used as key. The number
of rows in both selections
don't have to be equal. If there's no matching row in the
second selection
as in the first selection
the next older one will be used. The result has asmany rows
as the first selection. Also the
timestamps of the result come from the first selection. Important is
that also the first row in the first selection
finds a matching row in the second one, this means a a row with the same timestamp
or an older one. pdx produces an error if this
condition is not fulfilled. These four implementations are especially useful if there are selections who are numerator and denominator of a quotioent, if you have values based on other ones, specific values. |
(+ {timestamp}
{time}) →
{timestamp} (- {timestamp} {time}) → {timestamp} |
These functions add or subtract a {time} from or to a
{timestamp}. |
(+ {string} {string} ...) → {string} | This function concatenates a number of at least
two {string}
parameters. The result is again a {string}. |
Example 1: (+ 2010-17-12-00:00:00 (days 3)) results in Dec 20, 2010 0:00
Example 2: selection a selection b (* (select "a") (select "b")) -------------------- -------------------- ----------------------------- 2009-11-17 12:38 9.3 2009-12-01 13:00 5.2 -> 5.2 * 9.3 = 2009-12-01 13:00 48.36 2009-12-02 13:00 5.7 -> 5.7 * 9.3 = 2009-12-02 13:00 53.01 2009-12-03 13:00 3.2 -> 3.2 * 9.3 = 2009-12-03 13:00 18.24 2009-12-03 19:17 8.4 2009-12-04 13:00 4.8 -> 4.8 * 8.4 = 2009-12-04 13:00 40.32 2009-12-05 13:00 5.7 2009-12-05 13:00 4.7 -> 5.7 * 4.7 = 2009-12-05 13:00 26.79 2009-12-06 13:00 5.3 -> 5.3 * 4.7 = 2009-12-06 13:00 30.21 |
Informations about
collections |
|
---|---|
(unit
{string}) → {string} |
This function
returns the unit of the collection which has been defined
during their creation. |
(purpose {string}) → {string} | This function returns the purpose of the collection. |
HbA1c |
|
---|---|
These
functions are spezific for diabetics. They calculate the
HbA1c value based on blood sugar values of the last 90 days.
This amount of data is mandatory in the collection. The
function HbA1c
rates all values in the collection
equal while HbA1c2
gives younger values a higher weight. The latter one is more
variable than the first. The common {string} parameter
names the collection
containing the blood sugar values. |
|
(HbA1c {string}) → {selection} | calculates HbA1c from (now), the result
has only one row |
(HbA1c {string} {timestamp}) → {selection} | calculates HbA1c from the specified {timestamp}, the result has only one row |
(HbA1c {string} {timestamp} {timestamp}) → {selection} | calculates HbA1c in the timespan from the first
{timestamp} to
the second {timestamp},
the result has as many rows as values in this timespan |
(HbA1c {string} {time}) → {selection} | calculates HbA1c in the timespan from (now)-{time} to (now), the result has as many rows as values in this timespan |
(HbA1c {string} {time} {timestamp}) → {selection} | calculates HbA1c in the timespan from {timestamp}-{time} to {timestamp}, the result has as many rows as values in this timespan |
(HbA1c2 {string}) → {selection} | (these five
implementations are strictly like the five ones above) |
(HbA1c2 {string} {timestamp}) → {selection} | |
(HbA1c2 {string} {timestamp} {timestamp}) → {selection} | |
(HbA1c2 {string} {time}) → {selection} | |
(HbA1c2 {string} {time} {timestamp}) → {selection} |
Berichte |
|
---|---|
The
functions of this group are needed for the creation of
reports. They return a character string, oftenly a
multi-line amount of text. pdx parses the report template,
sees an invication of format,
executes it and replaces this by the function result at
exactly the same position. These functions can truely be
tested in interactive mode. |
|
(format ...) → {string} | The format function
accepts an open parameter list consisting from text, function results, format specifications
and keywords: (format "<tr>" "<td>" datetime "</td>" "<td>" (select "*" (days 7)) <1.1> "</td>" "<td>" (select "n" (days 7)) <1> "</td>" "</tr>" newline ) All these expressions result in short pieces of text being concatenated. The result is a one or multi-line piece of text in any length. The number of lines in it depends on the number of values in the function results. If values do match by their timestamps they are placed on the same line. The keyword datetime is a placeholder for the timestamp of the line. The keyword newline inserts a physical linebreak. The format specifications can be recognized by their angle brackets. They always apply to the value directly before. There are three different formats:
[...] <tr><td>2009-01-17 21:42:49</td><td>5.6</td><td>6</td></tr> <tr><td>2009-01-18 05:54:41</td><td>6.8</td><td>7</td></tr> <tr><td>2009-01-18 12:17:22</td><td>5.4</td><td>6</td></tr> [...] |
(empty {string}) → {string} | In a complex format function invocation sometimes
there's the problem to place even empty values in the output
represented by something visible. Empty values appear by
joining multiple selections
to a table (outer join).
Using the empty
function we can tell the format function what {string} to use for
empty values in in the output. |
Diagramme |
|
---|---|
The
following functions draw something visible into a diagram.
They can't be tested in interactive mode
of pdx. The result is always {nothing}, we can't use it for further
calculations. |
|
(diagram {int} {int}
{color} ...) → {nothing} |
The diagram function is a wrapper. It
surrounds the definition of a concrete diagram. The first {int} parameter
specifies the size of the diagram in x-direction, the second
one the size in y-direction. The {color}
parameter specifies the background color
in RGB notation. The following open parameter list should
contain invocations of other diagramm functions especially
at least one axes
and one curve function. |
(sundays
{color}) → {nothing} |
The function tells pdx that sundays should get a
color on the time axis. This makes only sense if the time
axis really shows days. The sundays function must be called before
the axes
function. Otherwise it will not work. |
The four implementations of the axes function draw a complete and labelled coordinate system. The user has not to worry about the details. The three commonly used {double} parameters are 1) the lower bound of the y-axis, 2) the upper bound of the y-axis, 3) the line width of the axes. The {color} parameter names the color of the axes and their labels. The {string} parameter at the end can contain a short text that is displayed on top of the y-axis. Normally this should be a unit. | |
(axes {timestamp}
{timestamp} {double} {double} {double} {color} {string}) → {nothing} |
x-axis in the timespan between the two {timestamp}
parameters |
(axes {time} {timestamp}
{double} {double} {double} {color} {string}) → {nothing} |
x-axis in the timespan between {timestamp}-{time}
and {timestamp} |
(axes {time} {double}
{double} {double} {color} {string}) → {nothing} |
x-axis in the timespan between (now)-{time} and (now) |
(axes keyword {double}
{double} {double} {color} {string}) → {nothing} |
with keyword
= year, month, day, hour or minute, especially
for drawing data resulting of a call to the fold function. You
need the same interval here. |
The
following functions draw "curves" into the diagram to make
values visible. |
|
(curve {selection}
{color}) → {nothing} |
The function draws a zigzag line in the given color and in a predefined line thickness. |
(curve {selection}
{color} {double}) → {nothing} |
Like above. The {double} parameter contains the desired line thickness: values >1 lead to bold lines, values <1 to thinner ones. |
(curve {selection}
{color} {string}) → {nothing} |
The function draws a curve consisting from separate, unlinked dots in the given color and in a predefined line thickness. The {string} parameter names the symboles used to represent the dots. The following specifications are allowed: ".", "+", "|", "-", "x", "X", "°" or "#". |
(curve {selection}
{color} {string} {double}) → {nothing} |
Like above. The {double} parameter contains the desired line thickness: values >1 lead to bold lines, values <1 to thinner ones. |
(bars {selection}
{color}) → {nothing} |
The function draws vertical bars, one per value in the selection. This can lead to different numbers of bars in concrete, same length time intervals according to what the selection contains. In this case it has been found convenient to separate the time intervals slightly by color (this is done automatically). |
(bars {selection}
{color} {int} {int}) → {nothing} |
The function draws vertical bars having all the same width. The first {int} parameter contains - beginning at 1 - the number of the bar in an interval, the second {int} parameter contains the total number of bars in an interval. Setting these {int} parameters correctly and using multiple calls to the bars function several selections can be placed as colored bars one beside the other. |
(stairs
{selection} {color}) → {nothing} |
The function draws a line in stairs. This means
all parts of the line are either horizontal or vertical. |
(stairs
{selection} {color} {double}) → {nothing} |
Like above. The {double} parameter contains the desired
line thickness. |
The
two implementations of the hline function
draw a horizontal line in der specified color. |
|
(hline {double} {color}) → {nothing} |
{double}
specifies the position of the line on the y-axis |
(hline {double} {double}
{color}) → {nothing} |
the first {double}
parameter specifies the position of the line on the y-axis,
the second one determines the line width |
The two implementations of the hline function draw a vertical line in der specified color. | |
(vline {timestamp}
{color}) → {nothing} |
{timestamp}
specifies the position of the line on the x-axis |
(vline {timestamp}
{double} {color}) → {nothing} |
{timestamp} specifies the position of the line on the x-axis, {double} determines the line width |
(vline {time} {color}) → {nothing} |
{time} specifies the position of the line on the x-axis, especially for drawing data resulting of a call to the fold function |
(vline {time} {double}
{color}) → {nothing} |
{time} specifies the position of the line on the x-axis, {double} determines the line width, especially for drawing data resulting of a call to the fold function |
Examples: (diagram 500 375 #FFFDFD (axes day 3.0 9.0 1.0 #0 (unit "*")) (hline 4.5 #C0C0C0) (hline 5.0 #C0C0C0) (hline 5.5 #C0C0C0) (hline 6.0 #C0C0C0) (hline 6.5 #C0C0C0) (hline 7.0 #C0C0C0) (hline 7.5 #C0C0C0) (vline 5:45 #C0C0C0) (vline 12:30 #C0C0C0) (vline 18:30 #C0C0C0) (vline 21:30 #C0C0C0) (curve (fold day first (merge avg (select "*" (week)) (select "x" (week)))) #FF0000 "+") (curve (avg (fold day first (merge avg (select "*" (week)) (select "x" (week)))) 3 3) #000000 2.0) (curve (avg (fold day first (merge avg (select "*" (year)) (select "x" (year)))) 30 30) #000000) ) (diagram 500 375 #FFFDFD (axes (month 1) 0.0 17.0 1.0 #0 (unit "n")) (bars (select "n" (month 1)) #FF1000) ) (diagram 500 375 #FFFDFD (axes (month 1) 0.0 17.0 1.0 #0 (unit "n")) (bars (sum (select "n" (month 1)) day 3:30 11:00) #FF1000 1 4) (bars (sum (select "n" (month 1)) day 11:00 14:30) #FF5000 2 4) (bars (sum (select "n" (month 1)) day 14:30 17:30) #FF5000 3 4) (bars (sum (select "n" (month 1)) day 17:30 21:00) #FF9000 4 4) ) |
other |
|
---|---|
(build) → {string} | The function
gets the build-string from pdx. This string contains
informations about when and how pdx has been compiled, this
means which options have been used and which optional
features are supported. |
(database) → {string} | The function gets name and version of the
database system below. |
(version) → {string} | The function gets the version of pdx. |
Examples: (build) Dec 15 2010, 17:25:30, USE_SQLITE,
USE_MYSQL, USE_READLINE, USE_BOARD, USE_CAIRO, USE_ETPAN
(database) MySQL 5.1.51
(version) 1.2.0
|
pdx Configuration | Index | pdx Interactive Mode |