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. |
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}. |
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 |
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. |
|
(axes
{timestamp}
{timestamp}
{double}
{double}
{double}
{color}) → {nothing} |
x-axis
in
the
timespan
between
the
two
{timestamp}
parameters |
(axes
{time}
{timestamp}
{double}
{double}
{double}
{color}) → {nothing} |
x-axis
in
the
timespan
between
{timestamp}-{time}
and {timestamp} |
(axes
{time}
{double}
{double}
{double}
{color}) → {nothing} |
x-axis in the timespan between (now)-{time} and (now) |
(axes
keyword
{double}
{double}
{double}
{color}) → {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) (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) (bars (select "n" (month 1)) #FF1000) ) (diagram 500 375 #FFFDFD (axes (month 1) 0.0 17.0 1.0 #0) (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 |