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 curvefunction. |
(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 ten different implementations of the axes function draw each a complete and labelled coordinate system the user has not to fight with. Generally: the less parameters an implementation has the more automatic it is. If there are more parameters the user can better an more precise determine how the axes should look alike. | |
(axes {timestamp} {timestamp}
{double} {double}
{double} {color}
{string}) → {nothing}
a (axes {time} {timestamp} {double} {double} {double} {color} {string}) → {nothing} b (axes {time} {double} {double} {double} {color} {string}) → {nothing} c (axes keyword {double} {double} {double} {color} {string}) → {nothing} d (axes {timestamp} {timestamp} {double} {color} {string}) → {nothing} e (axes {time} {timestamp} {double} {color} {string}) → {nothing} f (axes {time} {double} {color} {string}) → {nothing} g (axes keyword {double} {color} {string}) → {nothing} h (axes {double} {double} {double} {color} {string}) → {nothing} i (axes {double} {color} {string}) → {nothing} j |
|
Green parameters are
related to the x
axis:
Indeed the implementation j calculates both axes completely, so every value can be drawn and no one gets outside the dagram. The always existing red {double} parameter specifies the step width of the labels on the y axis. The {color} parameter tells the color of both axes and the labels. The {string} parameter at the end can contain a text which is displayed at the upper end of the y axis. This is usually a unit. |
|
The
following functions draw "curves" into the diagram to make values
visible. |
|
(curve {selection}
{color})
a → {nothing} |
The function draws a zigzag line in the given color and in a predefined line thickness. |
(curve {selection} {color}
{double})
b → {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})
c → {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}) d → {nothing} |
Like above. The {double} parameter contains the desired line thickness: values >1 lead to bold lines, values <1 to thinner ones. |
(spline {selection}
{color}
{int})
a → {nothing} |
Both
the implementations a and b of the
spline function are
very similar to the implementations a and b of the
curve function above.
The difference is that the spline algorithm used here tries to
compute additional values
between the given values. The resulting curve will consist
from much more points than we have originally available which
leads to much prettier, rounder curves. The aditional {int} parameter determines how
many values should be computed between two given values, in
example 5 or 10. Attention! To apply the spline function successfully an amount of valid input data is needed. Usually you can achieve good results if there are equidistant values in x direction. However, if there are values heaping up on some points in time - this is the case especially on folded x-axes - the spline function calculates fantastic and unexpected minima and maxima which never could be realistic. |
(spline {selection}
{color} {double} {int})
b → {nothing} |
|
(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
following functions draw horizontal lines in the specified
color. |
|
(hline {double}
{color}) → {nothing} |
These
two functions draw one horizontal line. The first {double} specifies the position
of the line on the y-axis, the second one determines the line
width. |
(hline {double} {double}
{color}) → {nothing} |
|
(hlines {double}
{color}) → {nothing} |
These
two functions draw as many horizontal lines as needed according to
the length of the y-axis. The first {double} specifies the step width
between the lines. You should use the same value as in the
axes function. The
second {double}
specifies the line width. |
(hlines {double} {double}
{color}) → {nothing} |
|
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 1.0 #0 (unit "n")) (bars (select "n" (month 1)) #FF1000) ) (diagram 500 375 #FFFDFD (axes 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 |