Read Me

PySOS: Generic SOS service for Relational databases

Bill Howe
NSF STC for Coastal Margin Observation and Prediction
Oregon Health and Science University

PySOS serves data in a relational database through the SOS interface, and is written entirely in Python.   We've deployed PySOS for serving data for NANOOS and the Center for Coastal Margin Observation and Prediction using Apache and PostgreSQL. Our own implementation is up and accessible. 

== Usage ==

If one's data is already in an RDBMS, this prototype should be deployable without great effort. Simply provide a SQL statement (or better yet, write a view) for each of four SOS concepts in the config file, ensuring they return tuples with the following schemes:

    * sos_offering(description, offering, shortname, srid, xmin, ymin, xmax, ymax, starttime, endtime, uri, featureOfInterest)
    * sos_observedproperty(offering, description, variable, mmiuri, featureOfInterest, uom)
    * sos_sensor([Identical to sos_offering -- The SOS standard may make this concept obsolete])
    * sos_observation(offering, observedproperty, time, lat, lon, depth, value)

I emulate these tables using views, so the queries in my config file are especially simple; e.g.,

SELECT * FROM sos_offering

where sos_offering is a view defined over our 'OOSDB' schema.

For current example queries against our SOS service, see
http://www.stccmop.org/node/306


== View Descriptions ==

=== sos_offering ===

An SOS offering is a logically coherent feed of observations.  All observations need not come from a single platform, but they often do.

Columns:
  description: Free-text description of the feed.  Appears in the XML metadata returned by the GetCapabilities response and the DescribeSensor response.
  offering: A short text identifier for the offering.  The offering "name."
  shortname: An optional local name for the offering. 
  srid: The EPSG identifier for the geodesic coordinate system used. Appears in the XML wherever spatial coordinates are used.  The term 'srid' comes from the PostGIS extensions to the postgres database.
  xmin: The lower left x-coordinate of the offering bounding box (see note on "Bounding Box" below). 
  ymin: The lower left y-coordinate of the offering's bounding box (see note on "Bounding Box" below). 
  xmax: The upper right x-coordinate of the offering's bounding box (see note on "Bounding Box" below). 
  ymax: The upper right y-coordinate of the offering's bounding box (see note on "Bounding Box" below). 
  starttime: The earliest time for which data is available for this offering.  Date and time are combined in one field, as recommended by ISO and supported by PostgreSQL and MySQL.
  endtime: The latest time for which data is available for this offering.
  uri: A web-resolvable identifier for this offering.  Appears in the GetCapabilities, DescribeSesnsor, and GetObservation responses.
  featureOfInterest: An SOS concept that identifies the medium being observed.  An example we have used is 'urn:something:bodyOfWater', but the SOS standard has been refined.

Notes:

Bounding Box:  In PySOS, all geometric extents are modeled as a 2D bounding box.  The GML dialectadopted by the SOS standard supports more complicated geometric types (points, polygons, etc.), but bounding boxes are the simplest mechanism that covers all the cases. For a fixed station, a degenerate bounding box with identical lower left and upper right corners is acceptable.  These columns are required to properly geolocate the offerings on a map.

=== sos_observedproperty ===

The variables measured by each offering.  

Columns:
  offering: The offering identifier.  Must appear as an entry in the "offering" column of the sos_offering view.
  observedproperty: The standard name of the variable.
  variable: A short name of the variable.
  description: A free-text description of the variable.
  mmiuri: A standarized uri for the variable name. One potential source for standard variable names is http://marinemetadata.org/cf, which is where the name "mmiuri" originates.
  featureOfInterest: An SOS concept that identifies the medium being observed.  An example we have used is 'urn:something:bodyOfWater', but the SOS standard has been refined.
  uom: Text representing the unit of measure.  

=== sos_sensor ===

Identical to sos_offering.  The two concepts are potentially distinct, which is why we provide a separate query, but most applications unify them, and the 0.0.3 SOS standard is vague on the issue.

Columns:
  Identical to sos_offering

=== sos_observation ===

The table of observations.  This view represents a pivoted view of the data, such that different variables are modeled as separate tuples.  This form was dictated by the early SOS applications. As an example, consider a CT observation:

  offering, time, latitude, longitude, depth, salinity, temperature
  -----------------------------------------------------------------
  o1,       t1,   lat1,     lon1,      d1,    sal1,     tem1

This single tuple becomes two tuples, one for each variable measured:

  offering, observedproperty, time, latitude, longitude, depth, value
  -------------------------------------------------------------------
  o1,       'salinity',       t1,   lat1,     lon1,      d1,    sal1
  o1,       'temperature',    t1,   lat1,     lon1,      d1,    tem1

This pivoting is difficult to express in SQL, requiring an N-way union, where N is the number of variables.  
In SOS 1.0.0, it is possible to request multiple variables at one time.  PySOS does not currently support this mechanism, but is expected to.

Columns:
  offering: The offering identifier. Must appear as an entry in the "offering" column of the sos_offering view.
  observedproperty: The variable being measured.  (offering, observedproperty) must appear in the records returned by sos_observedproperty. That is, observations should only appear for variables that an offering actually measures.
  time: The time that the observation was made.  Date and time are combined in one field as recommended by ISO and supported by PostgreSQL and MySQL.
  lat: The latitude at which the observation was collected.  The dependence on latitude and longitude is an artifact of the early SOS applications.  
  lon: The longitude at which the observation was collected.  The dependence on latitude and longitude is an artifact of the early SOS applications.  
  depth: The depth at which the observation was collected.
  value: The measured value of the variable.
 
== Installation ==

see INSTALL