cartodb4/observatory-extension
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge branch 'release_v1_api_functions' into get_obs_json_version

Browse Source
This commit is contained in:
John Krauss
2016-04-25 15:35:49 -04:00
parent b93ea03786 1d9e37fd60
commit 4e87eae904
4 changed files with 82 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
doc/methods.md
View File

@@ -18,27 +18,24 @@ normalize | for measures that are are **sums** (e.g. population) the default nor
#### Returns
A JSON object containing the following properties
A NUMERIC value containing the following properties
Key | Description
--- | ---
value | the raw or normalized measure
name | the human readable name of the measure
description | a brief description of the measure
type | the data type (text, number, boolean)
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population') -> 'value'
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population')
```
Get a measure at a single point location
```SQL
SELECT * FROM json_each(OBS_GetUSCensusMeasure(CDB_LatLng(40.7, -73.9), 'Male Population'))
SELECT OBS_GetUSCensusMeasure(CDB_LatLng(40.7, -73.9), 'Male Population')
```
<!--
@@ -48,7 +45,7 @@ Should add the SQL API call here too
## OBS_GetUSCensusMeasure(polygon_geometry, measure_name);
The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` method returns a measure based on a subset of the US Census variables within a given polygon. The ```OBS_GetUSCensusMeasure``` method is limited to only a subset of all measures that are available in the Data Observatory, to access the full list, use the ```OBS_GetMeasure``` method below.
The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` method returns a measure based on a subset of the US Census variables within a given polygon. The ```OBS_GetUSCensusMeasure``` method is limited to only a subset of all measures that are available in the Data Observatory, to access the full list, use the ```OBS_GetUSCensusMeasure``` method below.
#### Arguments
@@ -60,27 +57,61 @@ normalize | for measures that are are **sums** (e.g. population) the default nor
#### Returns
A JSON object containing the following properties
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
name | the human readable name of the measure
description | a brief description of the measure
type | the data type (text, number, boolean)
#### Example
Add a Measure to an empty column based on polygons in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population') -> 'value'
UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population')
```
Get a measure at a single polygon
```SQL
SELECT * FROM json_each(OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), 'Male Population'))
SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), 'Male Population')
```
<!--
Should add the SQL API call here too
-->
## OBS_GetUSCensusCategory(point_geometry, measure_name);
The ```OBS_GetUSCensusCategory(point_geometry, category_name)``` method returns a categorical measure based on a subset of the US Census variables at a point location. It requires a different function from ```OBS_GetUSCensusMeasure``` because this function will always return TEXT, whereas ```OBS_GetUSCensusMeasure``` will always returna NUMERIC value.
#### Arguments
Name |Description
--- | ---
point_geometry | a WGS84 point geometry (the_geom)
measure_name | a human readable string name of a US Census variable. The glossary of measure_names is [available below]('measure_name table').
#### Returns
A NUMERIC value containing the following properties
Key | Description
--- | ---
value | the raw or normalized measure
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetUSCensusCategory(the_geom, 'Spielman Singleton Category 10')
```
Get a measure at a single point location
```SQL
SELECT OBS_GetUSCensusCategory(CDB_LatLng(40.7, -73.9), 'Spielman Singleton Category 10')
```
<!--
@@ -101,27 +132,24 @@ normalize | for measures that are are **sums** (e.g. population) the default nor
#### Returns
A JSON object containing the following properties
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
name | the human readable name of the measure
description | a brief description of the measure
type | the data type (text, number, boolean)
#### Example
Add a Measure to an empty column based on point locations in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006') -> 'value'
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006')
```
Get a measure at a single point location
```SQL
SELECT * FROM json_each(OBS_GetMeasure(CDB_LatLng(40.7, -73.9), '"us.census.acs".B08134006'))
SELECT OBS_GetMeasure(CDB_LatLng(40.7, -73.9), '"us.census.acs".B08134006')
```
<!--
@@ -143,27 +171,26 @@ normalize | for measures that are are **sums** (e.g. population) the default nor
#### Returns
A JSON object containing the following properties
A NUMERIC value
Key | Description
--- | ---
value | the raw or normalized measure
name | the human readable name of the measure
description | a brief description of the measure
type | the data type (text, number, boolean)
#### Example
Add a Measure to an empty column based on polygons in your table
```SQL
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006') -> 'value'
UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, '"us.census.acs".B08134006')
```
Get a measure within a polygon
```SQL
SELECT * FROM json_each(OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), '"us.census.acs".B08134006'))
SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), '"us.census.acs".B08134006')
```
<!--

20
src/pg/sql/40_observatory_utility.sql
View File

@@ -177,3 +177,23 @@ BEGIN
return result;
END;
$$ LANGUAGE plpgsql;
-- Function that replaces all non digits or letters with _ trims and lowercases the
-- passed measure name
CREATE OR REPLACE FUNCTION cdb_observatory._OBS_StandardizeMeasureName(measure_name text)
RETURNS text
AS $$
DECLARE
result text;
BEGIN
-- Turn non letter or digits to _
result = regexp_replace(measure_name, '[^\dA-Za-z]+','_', 'g');
-- Remove duplicate _'s
result = regexp_replace(result,'_{2,}','_', 'g');
-- Trim _'s from beginning and end
result = trim(both '_' from result);
result = lower(result);
RETURN result;
END;
$$ LANGUAGE plpgsql;

7
src/pg/test/expected/40_observatory_utility_test.out
View File

@@ -143,6 +143,13 @@ SELECT cdb_observatory._OBS_GetRelatedColumn(
{"\"es.ine\".total_pop",NULL,"\"us.census.acs\".B01001001"}
(1 row)
-- should give back a standardized measure name
SELECT cdb_observatory._OBS_StandardizeMeasureName('test 343 %% 2 qqq }}{{}}');
_obs_standardizemeasurename
-----------------------------
test_343_2_qqq
(1 row)
\i test/sql/drop_fixtures.sql
SET client_min_messages TO NOTICE;
\set ECHO none

3
src/pg/test/sql/40_observatory_utility_test.sql
View File

@@ -90,4 +90,7 @@ SELECT cdb_observatory._OBS_GetRelatedColumn(
'denominator'
);
-- should give back a standardized measure name
SELECT cdb_observatory._OBS_StandardizeMeasureName('test 343 %% 2 qqq }}{{}}');
\i test/sql/drop_fixtures.sql