Get Started

Install the latest release with conda

The easiest and most reliable way to install the ODM2 Python API package (odm2api) is using the **Conda** package management system via either Anaconda or Miniconda. To start using conda (if it’s not your system default), add conda to the PATH; on OS X and Linux, it’s something like export PATH=$HOME/miniconda3/bin:$PATH, but the exact path may vary.

To activate a conda environment, say, “myenv”:

activate myenv  # On Windows
source activate myenv  # On MacOSX or Linux

Note: odm2api currently is only tested on Python 2.7. Some changes have been made to support Python 3.x, but they haven’t been tested thoroughly.

Install the conda package

The latest release is available as a package on the conda-forge anaconda.org channel for all major OS platforms (linux, OS X, win32/win64). To install it on an existing conda environment:

conda install -c conda-forge odm2api

All dependencies are installed, including Pandas and its dependencies (numpy, etc).

To create a new environment “myenv” with the odm2api package:

conda create -n myenv -c conda-forge python=2.7 odm2api

Sample Jupyter notebooks

These two notebooks are complete, extended examples that illustrate reading from ODM2 databases and using the resulting data and metadata. They use SQLite ODM2 file databases that can be downloaded here. A conda environment to run these notebooks can be created with the conda environment file clientenvironment.yml.

  1. WaterQualityMeasurements_RetrieveVisualize.ipynb

  2. TimeSeries_RetrieveVisualize.ipynb

Code examples

Connecting to an ODM2 database

Connect to an ODM2 database and open the connection for reading.

from odm2api.ODMconnection import dbconnection
import odm2api.services.readService as odm2rs

# -----------------------------------------------------
# 1. A SQLite file-based connection
session_factory = dbconnection.createConnection('sqlite',
                                                '/myfilepath/odm2db.sqlite')
read = odm2rs.ReadODM2(session_factory)

# -----------------------------------------------------
# 2. A server-based database system connection
db_credentials = {
    'address': 'ip-or-domainname',
    'db': 'dbname',
    'user': 'dbuser',
    'password': 'password'
}
session_factory = dbconnection.createConnection('postgresql',
                                                **db_credentials)
read = odm2rs.ReadODM2(session_factory)

Updating an entity (table)

The update services have not been fleshed out at this time, for the most part. However, updates can be easily accomplished by reusing the connection setup at the start of an odm2api session, then constructing and issuing a direct SQL UPDATE statement, like this:

from odm2api.ODMconnection import dbconnection

session_factory = dbconnection.createConnection('postgresql',
                                                **db_credentials)
DBSession = session_factory.getSession()

sq_str = " UPDATE mytable SET variablecode = 'xyz' WHERE variablecode = 'abc' "
DBSession.execute(sql_str)
DBSession.commit()