Other Interfaces to RBB

This page documents tips on integrating with other languages, that don't need a full tutorial. Generally they don't (yet) offer a full read/write interface to RBB.

Outline

  1. Spreadsheet CSV Text File
  2. Matlab
  3. TCX - Garmin Training Center XML

Spreadsheet

To export to a spreadsheet such as Microsoft Excel:
  1. Run RBB get with the -csv option and store the output in a file with the extension .csv:
    java -jar rbb.jar get -csv jdbc:h2:mydb color=blue > t.csv
  2. In Excel, choose Import... CSV file... (Choose the file)... Delimited... Tab. (Make sure Tab is the only delimiter, since comma may also be selected by default.)

Matlab's Database Toolbox

This section shows how to import data from RBB to Matlab for numerical processing using the Database Toolbox for Matlab. This uses the SQL interface to RBB. (Matlab can call Java functions directly; example code to do this is welcome).

Connecting to the RBB

javaaddpath('/<path>/h2.jar')
javaaddpath('/<path>/rbb.jar') % necessary for embedded access (jdbc:h2:file:...) but not for server access (jdbc:h2:tcp:...)
rbb=database('', 'sa', 'x', 'org.h2.Driver', 'jdbc:h2:file:/<path>/mydb')

Retrieve Information About All Events

setdbprefs('datareturnformat','cellarray'); % this is the default, but might have been overwritten
fetch(rbb, 'select RBB_TAGSET_TO_STRING(TAGS), DATA_SCHEMA, DATA_TABLE from rbb_find_timeseries(null,null,null,null)')
Note: One issue with using RBB through Matlab is that Matlab doesn't support the ARRAY SQL type, which RBB uses often. For example, RBB Tagsets are passed as arrays of strings. RBB_TAGSET_TO_STRING converts the tagset array to a single string.

Find Events Matching a Tagset

To find only the timeseries with the tags test=draw, call:
fetch(rbb, 'select RBB_TAGSET_TO_STRING(TAGS), DATA_SCHEMA, DATA_TABLE from rbb_find_timeseries(RBB_TAGSET_FROM_STRING(''test=draw''),null,null,null)') 

Retrieve Columns From a Timeseries Into An Array

An simple example that retrieves the x,y coordinates of timeseries table S3:
setdbprefs('datareturnformat','numeric');
fetch(rbb, 'select C1, C2 from RBB_TIMESERIES.S3;')

Retrieve Time and Samples Into Separate Arrays

The previous example could also retrieve the time by adding TIME to the column list, but it would be stored in the same array as the Samples. To retrieve the timestamps into a separate array (without two separate queries), use Matlab's database cursor object:
setdbprefs('datareturnformat','numeric');
c=exec(rbb, 'select TIME, C1, C2 from RBB_TIMESERIES.S3;')
c=fetch(c) % retrieve the data table from the ResultSet without opening a second cursor object
t=c.Data(:,1) % column 1 contains time
xy=c.Data(:,2:3) % columns 2 and 3 contain x, y coordinates.

Resample Multiple Timeseries at a Fixed Frequency

This example resamples two concurrent timeseries (with IDs 3 and 6) to get snapshots at a fixed frequency of 0.1 hz.
setdbprefs('datareturnformat','numeric');
c=exec(rbb, 'select TIME, array_get(C1,1), array_get(C1,2), array_get(C2,1), array_get(C2,2) from rbb_timeseries_values((3, 6), null, null, 0.1, null);')
c=fetch(c)
t=c.Data(:,1)
s3=c.Data(:,2:3)
s6=c.Data(:,4:5)
Note:The query is complicated because it uses the sql function array_get to place each dimension of each timeseries in a separate column. If this is not done, each column of the ResultSet of rbb_timeseries_values contains a SQL Array, which is displayed in Matlab as a java object handle.

Iterate Over Multiple Timeseries Matching a Tagset

This example retrieves all the samples for timeseries with the tag type=a during the times that events with tags type=b also exist:
setdbprefs('datareturnformat','numeric');
% get the IDs of sets of events that co-occur
IDS=fetch(rbb, 'select ARRAY_GET(IDS,1), ARRAY_GET(IDS,2) from rbb_concurrent_events(((''type'',''a''),(''type'',''b'')), null, null, null, null)')
% retrieve timeseries values from the type=a timeseries events.
for i=1:size(IDS,1); A=fetch(rbb, sprintf('select ARRAY_GET(C1,1), ARRAY_GET(C1,2) from rbb_timeseries_values((%d,%d),null,null,null,null);', IDS(i,1), IDS(i,2))); disp(A); end

TCX - Garmin Training Center XML

This perl script will convert Garmin Training Center Files to RBB timeseries.

Here is a sequence of example commands to read in several .tcx files, and then create a time coordinate for each session so they can be easily compared:

DB=jdbc:h2:runningRBB
java -jar rbb.jar create $DB
time for i in *.tcx; do echo "reading $i" >&2; tcx2rbb $i; done | $RBB put -mux $DB
java -jar rbb.jar defineTimeCoordinate $DB timeCoordinate=secondsUTC 1 0
java -jar rbb.jar defineTimeCoordinatesForEventCombinations $DB sessionMinutes id 0.0166667
Note: rbb put requires the -mux option to read the output from tcx2rbb, because it creates separate timeseries for position, heart rate, and elevation in one pass.

Then you can use a draw commmand to view the data:

java -jar rbbjars/rbb-1.7.5.jar ui draw -map Topo -filterTags year=2012,month=10,units=latlong -filterTagsMulti id,units=latlong -speed 10 -timeCoordinate timeCoordinate=sessionMinutes $DB
Note: Mapping requires web access; if you are behind a proxy you may need to run java -Dhttp.proxyHost=<yourproxy> -Dhttp.proxyPort=<X>

Then select Show Paths and Zoom to Fit:

In this example each dot shows the position of the runner 30 minutes into the run on a different day.