Merge pull request #103 from CartoDB/develop

Version 0.0.5

NEWS.md

@@ -1,3 +1,28 @@
-0.0.1 (open date)
+0.0.5 (5/27/2016)
+-----
+* Adds new function `OBS_GetMeasureById` ([#96](https://github.com/CartoDB/observatory-extension/pull/96))
+
+0.0.4 (5/25/2016)
+-----
+* Updates queries involving US Census measure tags to be more generic ([#95](https://github.com/CartoDB/observatory-extension/pull/95))
+* Fixes tests which relied on an erroneous subset of block groups ([#95](https://github.com/CartoDB/observatory-extension/pull/95))
+
+0.0.3 (5/24/2016)
+-----
+* Generalizes internal queries to properly pull from multiple named geometry references
+* Adds tests for Who's on First boundaries
+* Improves automatic fixtures testing script
+
+0.0.2 (5/19/2016)
+-----
+* Adds Data Observatory exploration functions
+* Adds Data Observatory boundary functions
+* Adds Data Observatory measure functions
+* Adds script to generate fixtures for tests
+* Adds script for the automatic testing of metadata
+* Adds full documentation for all included functions
+* removes `cartodb` extension dependency
+
+0.0.1 (5/19/2016)
 ------------------
-* First iteration of `OBS_GetDemographicSnapshot(location Geometry(Point,4326))`;
+* First iteration of `OBS_GetDemographicSnapshot(location Geometry(Point,4326))`

doc/license.md

@@ -14,5 +14,5 @@ Natural Earth  |  [http://www.naturalearthdata.com/about/terms-of-use/](http://w
 Quattroshapes  |  [https://github.com/foursquare/quattroshapes/blob/master/LICENSE.md](https://github.com/foursquare/quattroshapes/blob/master/LICENSE.md)
 Zetashapes  |  [http://zetashapes.com/license](http://zetashapes.com/license)
 Spielman & Singleton  |  [https://www.openicpsr.org/repoEntity/show/41329](https://www.openicpsr.org/repoEntity/show/41329)
-Instituto Nacional de Estadistica  |  [http://www.ine.es/ss/Satellite?L=0&c=Page&cid=1254735849170&p=1254735849170&pagename=Ayuda%2FINELayout](http://www.ine.es/ss/Satellite?L=0&c=Page&cid=1254735849170&p=1254735849170&pagename=Ayuda%2FINELayout)
+El Instituto Nacional de Estadística (INE) | The National Statistics Institute (INE) of Spain includes data from multiple sources. If you are re-using their data, they explicitly require that you reference them accordingly<br /><br />[http://www.ine.es/ss/Satellite?L=0&c=Page&cid=1254735849170&p=1254735849170&pagename=Ayuda%2FINELayout](http://www.ine.es/ss/Satellite?L=0&c=Page&cid=1254735849170&p=1254735849170&pagename=Ayuda%2FINELayout)
 

doc/measures_functions.md

@@ -134,6 +134,40 @@ SET household_count = OBS_GetMeasure(the_geom, 'us.census.acs.B11001001')
 
 * If an unrecognized normalization type is input, raise an error: `'Only valid inputs for "normalize" are "area" (default) and "denominator".`
 
+## OBS_GetMeasureById(geom_ref text, measure_id text, boundary_id text)
+
+The ```OBS_GetMeasureById(geom_ref, measure_id, boundary_id)``` function returns any Data Observatory measure that corresponds to the boundary in ```boundary_id``` that has a geometry reference of ```geom_ref```.
+
+#### Arguments
+
+Name |Description
+--- | ---
+geom_ref | a geometry reference (e.g., a US Census geoid)
+measure_id | a measure identifier from the Data Observatory ([see available measures](https://cartodb.github.io/bigmetadata/observatory.pdf))  
+boundary_id | source of geometries to pull measure from (e.g., 'us.census.tiger.census_tract')
+time_span (optional) | time span of interest (e.g., 2010 - 2014). If `NULL` is passed, the measure from the most recent data will be used.
+
+#### Returns
+
+A NUMERIC value
+
+Key | Description
+--- | ---
+value | the raw measure associated with `geom_ref`
+
+#### Example
+
+Add a measure to an empty column based on county geoids in your table
+
+```SQL
+UPDATE tablename
+SET household_count = OBS_GetMeasureById(geoid_column, 'us.census.acs.B11001001', 'us.census.tiger.county')
+```
+
+#### Errors
+
+* Returns `NULL` if there is a mismatch between the geometry reference and the boundary id such as using the geoid of a county with the boundary of block groups
+
 ## OBS_GetCategory(point geometry, category_id text)
 
 The ```OBS_GetCategory(point, category_id)``` function returns any Data Observatory Category value at a point location. The Categories available are currently limited to Segmentation categories. See the Segmentation section of the [Catalog](https://cartodb.github.io/bigmetadata/observatory.pdf) for more detail.

src/pg/observatory.control

@@ -1,5 +1,5 @@
 comment = 'CartoDB Observatory backend extension'
-default_version = '0.0.4'
+default_version = '0.0.5'
 requires = 'postgis'
 superuser = true
 schema = cdb_observatory

src/pg/sql/41_observatory_augmentation.sql

@@ -380,6 +380,53 @@ END;
 $$ LANGUAGE plpgsql;
 
 
+CREATE OR REPLACE FUNCTION cdb_observatory.OBS_GetMeasureById(
+  geom_ref TEXT,
+  measure_id TEXT,
+  boundary_id TEXT,
+  time_span TEXT DEFAULT NULL
+)
+RETURNS NUMERIC
+AS $$
+DECLARE
+  target_table TEXT;
+  colname TEXT;
+  measure_val NUMERIC;
+  data_geoid_colname TEXT;
+  test_query TEXT;
+BEGIN
+
+  SELECT x ->> 'colname', x ->> 'tablename' INTO colname, target_table
+  FROM cdb_observatory._OBS_GetColumnData(boundary_id, Array[measure_id], time_span) As x;
+
+  EXECUTE
+    format('SELECT ct.colname
+              FROM observatory.obs_column_to_column c2c,
+                   observatory.obs_column_table ct,
+                   observatory.obs_table t
+             WHERE c2c.reltype = ''geom_ref''
+               AND ct.column_id = c2c.source_id
+               AND ct.table_id = t.id
+               AND t.tablename = %L'
+     , target_table)
+  INTO data_geoid_colname;
+
+  RAISE DEBUG 'target_table %, colname %', target_table, colname;
+
+  EXECUTE format(
+      'SELECT %I
+       FROM observatory.%I
+       WHERE %I.%I = %L',
+       colname,
+       target_table,
+       target_table, data_geoid_colname, geom_ref)
+  INTO measure_val;
+
+  RETURN measure_val;
+
+END;
+$$ LANGUAGE plpgsql;
+
 CREATE OR REPLACE FUNCTION cdb_observatory.OBS_GetCategory(
   geom geometry(Geometry, 4326),
   category_id TEXT,

src/pg/test/expected/41_observatory_augmentation_test.out

@@ -76,3 +76,15 @@ t
 obs_getuscensuscategory_polygon
 t
 (1 row)
+obs_getmeasurebyid_cartodb_census_tract
+t
+(1 row)
+obs_getmeasurebyid_null_boundary_null_timespan
+t
+(1 row)
+obs_getmeasurebyid_cartodb_block_group
+t
+(1 row)
+obs_getmeasurebyid_nulls
+t
+(1 row)

src/pg/test/sql/41_observatory_augmentation_test.sql

@@ -204,4 +204,37 @@ SELECT cdb_observatory.OBS_GetUSCensusCategory(
   cdb_observatory._testarea(), 'Spielman-Singleton Segments: 10 Clusters') = 'Low income, mix of minorities' As OBS_GetUSCensusCategory_polygon;
 
 
+-- OBS_GetMeasureById tests
+-- typical query
+SELECT (cdb_observatory.OBS_GetMeasureById(
+  '36047048500',
+  'us.census.acs.B01003001',
+  'us.census.tiger.census_tract',
+  '2010 - 2014'
+) - 3241) / 3241 < 0.0001 As OBS_GetMeasureById_cartodb_census_tract;
+
+-- no boundary_id should give null
+SELECT cdb_observatory.OBS_GetMeasureById(
+  '36047048500',
+  'us.census.acs.B01003001',
+  NULL,
+  NULL
+) IS NULL As OBS_GetMeasureById_null_boundary_null_timespan;
+
+-- query at block_group level
+SELECT (cdb_observatory.OBS_GetMeasureById(
+  '360470485002',
+  'us.census.acs.B01003001',
+  'us.census.tiger.block_group',
+  '2010 - 2014'
+) - 1900) / 1900 < 0.0001 As OBS_GetMeasureById_cartodb_block_group;
+
+-- geom ref / boundary mismatch
+SELECT cdb_observatory.OBS_GetMeasureById(
+  '36047048500',
+  'us.census.acs.B01003001',
+  'us.census.tiger.block_group',
+  '2010 - 2014'
+) IS NULL As OBS_GetMeasureById_nulls;
+
 \i test/fixtures/drop_fixtures.sql