From 10ec53f08eb49ef741581e120af316ff2ce03ab7 Mon Sep 17 00:00:00 2001 From: andrewxhill Date: Tue, 10 May 2016 16:12:20 -0400 Subject: [PATCH] still need to review the GetCategory method with stuart after data deployment --- doc/measures_functions.md | 113 +++++++++++++------------------------- 1 file changed, 37 insertions(+), 76 deletions(-) diff --git a/doc/measures_functions.md b/doc/measures_functions.md index 32fd25d..226eeef 100644 --- a/doc/measures_functions.md +++ b/doc/measures_functions.md @@ -8,13 +8,13 @@ We show here how you can access Measures through the CartoDB Editor. The same me ## OBS_GetUSCensusMeasure(point geometry, measure_name text); -The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` function returns a measure based on a subset of the US Census variables at a point location. The ```OBS_GetUSCensusMeasure``` function 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``` function below. +The ```OBS_GetUSCensusMeasure(point, measure_name)``` function returns a measure based on a subset of the US Census variables at a point location. The ```OBS_GetUSCensusMeasure``` function 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``` function below. #### Arguments Name |Description --- | --- -point_geometry | a WGS84 point geometry (the_geom) +point | a WGS84 point geometry (the_geom) measure_name | a human readable name of a US Census variable. The list of measure_names is [available in the glossary](/cartodb-platform/dataobservatory/glossary/#obsgetuscensusmeasure-names-table). normalize | for measures that are are **sums** (e.g. population) the default normalization is 'area' and response comes back as a rate per square kilometer. Other options are 'denominator', which will use the denominator specified in the @@ -39,15 +39,15 @@ Should add the SQL API call here too --> -## OBS_GetUSCensusMeasure(polygon_geometry, measure_name); +## OBS_GetUSCensusMeasure(polygon geometry, measure_name text); -The ```OBS_GetUSCensusMeasure(point_geometry, measure_name)``` function returns a measure based on a subset of the US Census variables within a given polygon. The ```OBS_GetUSCensusMeasure``` function 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``` function below. +The ```OBS_GetUSCensusMeasure(point, measure_name)``` function returns a measure based on a subset of the US Census variables within a given polygon. The ```OBS_GetUSCensusMeasure``` function 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``` function below. #### Arguments Name |Description --- | --- -point_geometry | a WGS84 polygon geometry (the_geom) +polygon | a WGS84 polygon geometry (the_geom) measure_name | a human readable string name of a US Census variable. The list of measure_names is [available in the glossary](/cartodb-platform/dataobservatory/glossary/#obsgetuscensusmeasure-names-table). normalize | for measures that are are **sums** (e.g. population) the default normalization is 'none' and response comes back as a raw value. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](https://cartodb.github.io/bigmetadata/observatory.pdf) (optional) @@ -67,64 +67,20 @@ Add a Measure to an empty column based on polygons in your table UPDATE tablename SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population') ``` -Get a measure at a single polygon - -```SQL -SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), 'Male Population') -``` - +## OBS_GetMeasure(point geometry, measure_id text); -## OBS_GetUSCensusCategory(point_geometry, measure_name); - -The ```OBS_GetUSCensusCategory(point_geometry, category_name)``` function 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 list of measure_names is [available in the glossary](/cartodb-platform/dataobservatory/glossary/#obsgetuscensusmeasure-names-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') -``` - - - -## OBS_GetMeasure(point_geometry, measure_id); - -The ```OBS_GetMeasure(point_geometry, measure_id)``` function returns any Data Observatory measure at a point location. +The ```OBS_GetMeasure(point, measure_id)``` function returns any Data Observatory Measure at a point location. You can browse all available Measures in the [Catalog](https://cartodb.github.io/bigmetadata/observatory.pdf)). #### Arguments Name |Description --- | --- -point_geometry | a WGS84 point geometry (the_geom) -measure_id | a measure identifier from the Data Observatory ([see available measures](https://cartodb.github.io/bigmetadata/observatory.pdf)) +point | a WGS84 point geometry (the_geom) +measure_id | a measure identifier from the Data Observatory ([see available measures](https://cartodb.github.io/bigmetadata/observatory.pdf)). It is important to note that these are different than 'measure_name' used in the Census based functions above. normalize | for measures that are are **sums** (e.g. population) the default normalization is 'area' and response comes back as a rate per square kilometer. Other options are 'denominator', which will use the denominator specified in the [Data Catalog](https://cartodb.github.io/bigmetadata/observatory.pdf) and 'none' which will return a raw value. (optional) #### Returns @@ -140,23 +96,12 @@ value | the raw or normalized measure 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') +UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, 'us.census.acs.B08134006') ``` -Get a measure at a single point location +## OBS_GetMeasure(polygon geometry, measure_id text); -```SQL -SELECT OBS_GetMeasure(CDB_LatLng(40.7, -73.9), '"us.census.acs".B08134006') -``` - - - - -## OBS_GetMeasure(polygon_geometry, measure_id); - -The ```OBS_GetMeasure(polygon_geometry, measure_id)``` function returns any Data Observatory measure calculated within a polygon. +The ```OBS_GetMeasure(polygon, measure_id)``` function returns any Data Observatory Measure calculated within a polygon. #### Arguments @@ -179,17 +124,33 @@ value | the raw or normalized measure 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') +UPDATE tablename SET local_male_population = OBS_GetMeasure(the_geom, 'us.census.acs.B08134006') ``` -Get a measure within a polygon + +## 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. + +#### Arguments + +Name |Description +--- | --- +point | a WGS84 point geometry (the_geom) +category_id | a category identifier from the Data Observatory ([see available measures](https://cartodb.github.io/bigmetadata/observatory.pdf)). + +#### Returns + +A NUMERIC value + +Key | Description +--- | --- +value | a text based category found at the supplied point + +#### Example + +Add the Category to an empty column based on point locations in your table ```SQL -SELECT OBS_GetMeasure(ST_Buffer(CDB_LatLng(40.7, -73.9),0.001), '"us.census.acs".B08134006') - - +UPDATE tablename SET segmentation = OBS_GetCategory(the_geom, 'X55') ``` - -