Code-in-action

Click here to see actual sites based on OpenBasin technology.

Sample Code:

• Creating an OpenBasin Object
• Accessing the data using the $OpenBasin Object
• Accessing the data using a station object
• Qualifying the data returned
• Returning data from multiple stations
• Using a Dataset
• Using a Dataspan

• Data grouping
• Data buffering
• Automatic data conversions

Sample Code:

Creating an OpenBasin Object
Following is the standard way to start OpenBasin documents:

<?php
    require_once("ob_config.php");
    require_once("$OPENBASIN_OBJ_DIR/OpenBasin.php");

    // $DB_DBNAME is not necessary if $DB_DBNAME is 'openbasin'
    $OpenBasin =& new OpenBasin($DB_USERNAME, $DB_PASSWORD, $DB_DBNAME);
?>

Accessing the data using the $OpenBasin object
Using the $OpenBasin object directly:

<?php
    // $stationColumnsID is either a single station_columns_id or an array of station_columns_ids
    // A station_columns_id is a unique identifier for each specific column in the database

    // To get the latest database values:
    $dataset = $OpenBasin->getDatasetByStationColumnsID($stationColumnsID);

    // To get a time span of database values:
    $dataspan=$OpenBasin->getDataspanByStationColumnsID($stationColumnsID,'',$beginTime, $endTime);
?>

Accessing the data using a station object
Using the $OpenBasin object to create station objects:

<?php
    // $stationIdentifier is a short unique name that identifies a station from all others
    $station = $OpenBasin->makeStationObject($stationIdentifier);

    // $keyword is the name of a key created in the database and assigned to a number of different columns
    // For example, 'battery', 'water_flow', etc. could all be $keyword values.
    
    // To get the latest database values:
    $dataset = $station->getDatasetByKeyword($keyword);

    // To get a time span of database values:
    $dataspan = $station->getDataspanByKeyword($keyword, '', $beginTime, $endTime);
?>

<?php
    // Only return hourly data
    $station->timespanQualifier = 3600;

    // Only return data from tables specified as 'data' or 'calc' tables
    $station->tableDataQualifier = Array('data','calc');

    // Only return information from the 'station_hour' table
    $station->tableQualifier= 'station_hour';

    // Only return columns specified as 'min' or 'max'
    $station->dataTypeQualifier= Array('min','max');

    // Only return columns named 'h_avg_dg_batt_1'
    $station->columnQualifier = 'h_avg_dg_batt_1';
?>

Returning data from multiple stations
To return data from multiple stations, you must manually create a key object (as opposed to doing it through the station object) as follows:

<?php
    require_once("$OPENBASIN_OBJ_DIR/Key.php");
    
    // $keyword is the name of a key created in the database and assigned to a number of different columns
    // For example, 'battery', 'water_flow', etc. could all be $keyword values.
    $key =& new Key($keyword,$OpenBasin);
?>

<?php
    // Only return data from the database 'data_db'
    $key->databaseQualifier = 'data_db';

    // Only return data from either 'station_1' or 'station_2'
    $key->stationQualifer = Array('station_1','station_2');
?>

<?php
    require_once("$OPENBASIN_OBJ_DIR/Key.php");
    
    $key =& new Key('','',$OpenBasin);
?>

<?php
    require_once("$OPENBASIN_OBJ_DIR/Dataset.php");
    require_once("$OPENBASIN_OBJ_DIR/Dataspan.php");

    // To get the latest database values:
    $dataset =& new Dataset($key->getLatestValues(), $key->getGroups());

    // To get a time span of database values:
    $dataspan =& new Dataspan($key->getDataspan($beginTime, $endTime), $key->getGroups());
?>

Using a Dataset
The following shows multiple ways to retrieve data out of a dataset:

<?php
    while($value = $dataset1->getValue()){
        // Do something here
    }

    while(list($value, $units, $timestamp) = $dataset2->getData()){
        // Do something here
    }

    while($dataArray = $dataset3->getExtendedData()){
        list($value, $units, $timestamp, $timespan, $columnName, $stationColumnsID) = $dataArray;
        // Do something here
    }

    $value = $dataset->getValue($stationColumnsID);

    list($value, $units, $timestamp) = $dataset->getData($stationColumnsID);

    $dataArray = $dataset->getExtendedData($stationColumnsID);
    list($value, $units, $timestamp, $timespan, $columnName, $stationColumnsID) = $dataArray;
?>

Using a Dataspan
There are also multiple ways of using a dataspan:

<?php
    while($dataset = $dataspan->getDataset()){
        // Do something
    }

    while($array = $dataspan->getValue()){
        foreach($array as $tmp){
            $value = $tmp;
        }
    }

    while($array = $dataspan->getData()){
        foreach($array as $tmp){
            list($value, $units) = $tmp;
        }
    }

    while($array = $dataspan->getExtendedData()){
        foreach($array as $tmp){
            list($value, $units, $timestamp, $timespan, $columnName, $stationColumnsID) = $tmp;
        }
    }

    $dataset = $dataspan->getDataset($timestamp);

    $array = $dataspan->getValue($timestamp);

    $array = $dataspan->getData($timestamp);

    $array = $dataspan->getExtendedData($timestamp);
?>

Features:

Data grouping
One of the features of OpenBasin that makes it so easy to use is the built in data grouping feature. To summarize, when more than one qualif ier of any type is applied to the returned data, the data can be subdivided to include only the data in one group or the other. Below is an example simulating retrieving the hourly minimum, average, and maximum battery voltages from a given station object:

<?php
    $station =& $OpenBasin->makeStationObject('station');
    $station->timespanQualifier = 3600;  // Hourly data only
    $station->datatypeQualifier = Array('min','avg','max'); // Retrieve minimum, average, and maximum values
    $dataset = $station->getDatasetByKeyword('battery');

    $min_dataset = $dataset->getGroup('min');
    $avg_dataset = $dataset->getGroup('avg');
    $max_dataset = $dataset->getGroup('max');
?>

Data buffering
To increase the speed of the OpenBasin scripts and to reduce some of the database's workload, the OpenBasin object automatically buffers information that it will likely use again. This includes, column attributes, the latest database values, sensor objects, and more. Therefore, you can be more free with your code, because any call to database information that is made more than once in the same scripts is automatically retrieved from the buffer instead of querying the database again. Not only does this allow the website designer/programmer more freedom, but it reduces the workload on the server and the database.

Automatic data conversions
OpenBasin can handle automatic data conversions in multiple ways. The first is to create a PostgreSQL stored procedure and trigger to either automatically convert the data before it is inserted or add an additional column onto the database which will hold the converted value. In additon to that, you can create custom sensor objects for OpenBasin which perform the calculations and then associate them with columns requiring conversion, and OpenBasin will take care of the rest.

This means that regardless of the type of measurement made by the sensor, OpenBasin can be set up to return all the information in a common format. For example, if you have an air temperature sensor that measures in Farenheit and a soil temperature sensor that measures in Celcius, by simply making a few configurations to OpenBasin you will be able to return both values in either Farenheit or Celcius without additional programming. In fact, the website programmer does not even need to know which sensor measures Farenheit or Celcius. This feature does a great deal to simplify the programming process, and provide a more unified, standard data set.

You can learn more about creating custom sensor objects in the Creating new OpenBasin objects HOWTO or more about creating PostgreSQL stored procedures in the Creating new PostgreSQL stored procedures HOWTO. You may also find custom sensor objects and custom PostgreSQL stored procedures in the Plugins section of this website.

Sample Sites Using OpenBasin

www.bearriverbasin.org	Site for the Bear River Basin
www.duchesneriver.org	Site for the Duchesne/Strawberry River Water Users Association
www.spanishforkriver.org	Site for the Spanish Fork River Drainage in Utah

Know of another site? Let us know by emailing webmaster@openbasin.org.

technical contact: Matthew Maxwell
general contact:

Copyright © 2008 StoneFly Technology, Inc. All Rights Reserved.