Add new docs folder structure

2018-02-21 16:48:37 +01:00
parent 2183b7fc26
commit e07ee0b882
14 changed files with 2002 additions and 0 deletions
--- a/docs/examples/01-measures-functions.md
+++ b/docs/examples/01-measures-functions.md
@@ -0,0 +1,185 @@
+
+## Measures functions examples
+
+- Add a measure to an empty numeric column based on point locations in your table.
+
+```SQL
+UPDATE tablename
+SET total_population = OBS_GetUSCensusMeasure(the_geom, 'Total Population')
+
+
+- Add a measure to an empty numeric column based on polygons in your table
+
+```SQL
+UPDATE tablename
+SET local_male_population = OBS_GetUSCensusMeasure(the_geom, 'Male Population')
+```
+
+- Add a measure to an empty numeric column based on point locations in your table
+
+```SQL
+UPDATE tablename
+SET median_home_value_sqft = OBS_GetMeasure(the_geom, 'us.zillow.AllHomes_MedianValuePerSqft')
+```
+
+
+- Add a measure to an empty column based on polygons in your table
+
+```SQL
+UPDATE tablename
+SET household_count = OBS_GetMeasure(the_geom, 'us.census.acs.B11001001')
+```
+
+
+- Add the Category to an empty column text column based on point locations in your table
+
+```SQL
+UPDATE tablename
+SET segmentation = OBS_GetCategory(the_geom, 'us.census.spielman_singleton_segments.X55')
+```
+
+
+- Obtain metadata that can augment with one additional column of US population
+data, using a boundary relevant for the geometry provided and latest timespan.
+Limit to only the most recent column most relevant to the extent & density of
+input geometries in `tablename`.
+
+```SQL
+SELECT OBS_GetMeta(
+  ST_SetSRID(ST_Extent(the_geom), 4326),
+  '[{"numer_id": "us.census.acs.B01003001"}]',
+  1, 1,
+  COUNT(*)
+) FROM tablename
+```
+
+- Obtain metadata that can augment with one additional column of US population
+data, using census tract boundaries.
+
+```SQL
+SELECT OBS_GetMeta(
+  ST_SetSRID(ST_Extent(the_geom), 4326),
+  '[{"numer_id": "us.census.acs.B01003001", "geom_id": "us.census.tiger.census_tract"}]',
+  1, 1,
+  COUNT(*)
+) FROM tablename
+```
+
+- Obtain metadata that can augment with two additional columns, one for total
+population and one for male population.
+
+```SQL
+SELECT OBS_GetMeta(
+  ST_SetSRID(ST_Extent(the_geom), 4326),
+  '[{"numer_id": "us.census.acs.B01003001"}, {"numer_id": "us.census.acs.B01001002"}]',
+  1, 1,
+  COUNT(*)
+) FROM tablename
+```
+
+
+- Validate metadata with two additional columns of US census data; using a boundary relevant for the geometry provided and the latest timespan. Limited to the most recent column, and the most relevant, based on the extent and density of input geometries in `tablename`.
+
+```SQL
+SELECT OBS_MetadataValidation(
+  ST_SetSRID(ST_Extent(the_geom), 4326),
+  ST_GeometryType(the_geom),
+  '[{"numer_id": "us.census.acs.B01003001"}, {"numer_id": "us.census.acs.B01001002"}]',
+  COUNT(*)::INTEGER
+) FROM tablename
+GROUP BY ST_GeometryType(the_geom)
+```
+
+
+- Obtain population densities for every geometry in a table, keyed by cartodb_id:
+
+```SQL
+WITH meta AS (
+  SELECT OBS_GetMeta(
+    ST_SetSRID(ST_Extent(the_geom), 4326),
+    '[{"numer_id": "us.census.acs.B01003001"}]',
+    1, 1, COUNT(*)
+) meta FROM tablename)
+SELECT id AS cartodb_id, (data->0->>'value')::Numeric AS pop_density
+FROM OBS_GetData((SELECT ARRAY_AGG((the_geom, cartodb_id)::geomval) FROM tablename),
+                 (SELECT meta FROM meta))
+```
+
+- Update a table with a blank numeric column called `pop_density` with population
+densities:
+
+```SQL
+WITH meta AS (
+  SELECT OBS_GetMeta(
+    ST_SetSRID(ST_Extent(the_geom), 4326),
+    '[{"numer_id": "us.census.acs.B01003001"}]',
+    1, 1, COUNT(*)
+) meta FROM tablename),
+data AS (
+  SELECT id AS cartodb_id, (data->0->>'value')::Numeric AS pop_density
+  FROM OBS_GetData((SELECT ARRAY_AGG((the_geom, cartodb_id)::geomval) FROM tablename),
+                   (SELECT meta FROM meta)))
+UPDATE tablename
+SET pop_density = data.pop_density
+FROM data
+WHERE cartodb_id = data.id
+```
+
+- Update a table with two measurements at once, population density and household
+density.  The table should already have a Numeric column `pop_density` and
+`household_density`.
+
+```SQL
+WITH meta AS (
+  SELECT OBS_GetMeta(
+    ST_SetSRID(ST_Extent(the_geom),4326),
+    '[{"numer_id": "us.census.acs.B01003001"},{"numer_id": "us.census.acs.B11001001"}]',
+    1, 1, COUNT(*)
+) meta from tablename),
+data AS (
+  SELECT id,
+     data->0->>'value' AS pop_density,
+     data->1->>'value' AS household_density
+  FROM OBS_GetData((SELECT ARRAY_AGG((the_geom, cartodb_id)::geomval) FROM tablename),
+                   (SELECT meta FROM meta)))
+UPDATE tablename
+SET pop_density = data.pop_density,
+    household_density = data.household_density
+FROM data
+WHERE cartodb_id = data.id
+```
+
+
+- Obtain population densities for every row of a table with FIPS code county IDs
+(USA).
+
+```SQL
+WITH meta AS (
+  SELECT OBS_GetMeta(
+    ST_SetSRID(ST_Extent(the_geom), 4326),
+    '[{"numer_id": "us.census.acs.B01003001", "geom_id": "us.census.tiger.county"}]'
+) meta FROM tablename)
+SELECT id AS fips, (data->0->>'value')::Numeric AS pop_density
+FROM OBS_GetData((SELECT ARRAY_AGG(fips) FROM tablename),
+                 (SELECT meta FROM meta))
+```
+
+- Update a table with population densities for every FIPS code county ID (USA).
+This table has a blank column called `pop_density` and fips codes stored in a
+column `fips`.
+
+```SQL
+WITH meta AS (
+  SELECT OBS_GetMeta(
+    ST_SetSRID(ST_Extent(the_geom), 4326),
+    '[{"numer_id": "us.census.acs.B01003001", "geom_id": "us.census.tiger.county"}]'
+) meta FROM tablename),
+data as (
+  SELECT id AS fips, (data->0->>'value') AS pop_density
+  FROM OBS_GetData((SELECT ARRAY_AGG(fips) FROM tablename),
+                   (SELECT meta FROM meta)))
+UPDATE tablename
+SET pop_density = data.pop_density
+FROM data
+WHERE fips = data.id
+```
--- a/docs/examples/02-boundary-functions.md
+++ b/docs/examples/02-boundary-functions.md
@@ -0,0 +1,76 @@
+- Insert all Census Tracts from Lower Manhattan and nearby areas within the supplied bounding box to a table named `manhattan_census_tracts` which has columns `the_geom` (geometry) and `geom_refs` (text).
+
+```sql
+INSERT INTO manhattan_census_tracts(the_geom, geom_refs)
+SELECT *
+FROM OBS_GetBoundariesByGeometry(
+       ST_MakeEnvelope(-74.0251922607,40.6945658517,
+                      -73.9651107788,40.7377626342,
+                      4326),
+       'us.census.tiger.census_tract')
+```
+
+- Insert points that lie on Census Tracts from Lower Manhattan and nearby areas within the supplied bounding box to a table named `manhattan_tract_points` which has columns `the_geom` (geometry) and `geom_refs` (text).
+
+```sql
+INSERT INTO manhattan_tract_points (the_geom, geom_refs)
+SELECT *
+FROM OBS_GetPointsByGeometry(
+       ST_MakeEnvelope(-74.0251922607,40.6945658517,
+                       -73.9651107788,40.7377626342,
+                       4326),
+       'us.census.tiger.census_tract')
+```
+
+
+- Overwrite a point geometry with a boundary geometry that contains it in your table
+
+```SQL
+UPDATE tablename
+SET the_geom = OBS_GetBoundary(the_geom, 'us.census.tiger.block_group')
+```
+
+
+- Write the US Census block group geoid that contains the point geometry for every row as a new column in your table.
+
+```SQL
+UPDATE tablename
+SET geometry_id = OBS_GetBoundaryId(the_geom, 'us.census.tiger.block_group')
+```
+
+
+- Use a table of `geometry_id`s (e.g., geoid from the U.S. Census) to select the unique boundaries that they correspond to and insert into a table called, `overlapping_polygons`. This is a useful method for creating new choropleths of aggregate data.
+
+```SQL
+INSERT INTO overlapping_polygons (the_geom, geometry_id, point_count)
+SELECT
+  OBS_GetBoundaryById(geometry_id, 'us.census.tiger.county') As the_geom,
+  geometry_id,
+  count(*)
+FROM tablename
+GROUP BY geometry_id
+```
+
+
+- Insert into table `denver_census_tracts` the census tract boundaries and geom_refs of census tracts which intersect within 10 miles of downtown Denver, Colorado.
+
+```sql
+INSERT INTO denver_census_tracts(the_geom, geom_refs)
+SELECT *
+FROM OBS_GetBoundariesByPointAndRadius(
+  CDB_LatLng(39.7392, -104.9903), -- Denver, Colorado
+  10000 * 1.609, -- 10 miles (10km * conversion to miles)
+  'us.census.tiger.census_tract')
+```
+
+
+- Insert into table `denver_tract_points` points on US census tracts and their corresponding geoids for census tracts which intersect within 10 miles of downtown Denver, Colorado, USA.
+
+```sql
+INSERT INTO denver_tract_points(the_geom, geom_refs)
+SELECT *
+FROM OBS_GetPointsByPointAndRadius(
+  CDB_LatLng(39.7392, -104.9903), -- Denver, Colorado
+  10000 * 1.609, -- 10 miles (10km * conversion to miles)
+  'us.census.tiger.census_tract')
+```
--- a/docs/examples/03-discovery-functions.md
+++ b/docs/examples/03-discovery-functions.md
@@ -0,0 +1,160 @@
+
+```SQL
+SELECT * FROM OBS_Search('home value')
+```
+
+```SQL
+SELECT * FROM OBS_GetAvailableBoundaries(CDB_LatLng(40.7, -73.9))
+```
+
+- Obtain all numerators that are available within a small rectangle.
+
+```SQL
+SELECT * FROM OBS_GetAvailableNumerators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326))
+```
+
+- Obtain all numerators that are available within a small rectangle and are for
+the United States only.
+
+```SQL
+SELECT * FROM OBS_GetAvailableNumerators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), '{section/tags.united_states}');
+```
+
+- Obtain all numerators that are available within a small rectangle and are
+employment related for the United States only.
+
+```SQL
+SELECT * FROM OBS_GetAvailableNumerators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), '{section/tags.united_states, subsection/tags.employment}');
+```
+
+- Obtain all numerators that are available within a small rectangle and are
+related to both employment and age & gender for the United States only.
+
+```SQL
+SELECT * FROM OBS_GetAvailableNumerators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), '{section/tags.united_states, subsection/tags.employment, subsection/tags.age_gender}');
+```
+
+- Obtain all numerators that work with US population (`us.census.acs.B01003001`)
+as a denominator.
+
+```SQL
+SELECT * FROM OBS_GetAvailableNumerators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, 'us.census.acs.B01003001')
+WHERE valid_denom IS True;
+```
+
+- Obtain all numerators that work with US states (`us.census.tiger.state`)
+as a geometry.
+
+```SQL
+SELECT * FROM OBS_GetAvailableNumerators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, NULL, 'us.census.tiger.state')
+WHERE valid_geom IS True;
+```
+
+- Obtain all numerators available in the timespan `2011 - 2015`.
+
+```SQL
+SELECT * FROM OBS_GetAvailableNumerators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, NULL, NULL, '2011 - 2015')
+WHERE valid_timespan IS True;
+```
+
+- Obtain all denominators that are available within a small rectangle.
+
+```SQL
+SELECT * FROM OBS_GetAvailableDenominators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326));
+```
+
+- Obtain all denominators that are available within a small rectangle and are for
+the United States only.
+
+```SQL
+SELECT * FROM OBS_GetAvailableDenominators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), '{section/tags.united_states}');
+```
+
+- Obtain all denominators for male population (`us.census.acs.B01001002`).
+
+```SQL
+SELECT * FROM OBS_GetAvailableDenominators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, 'us.census.acs.B01001002')
+WHERE valid_numer IS True;
+```
+
+- Obtain all denominators that work with US states (`us.census.tiger.state`)
+as a geometry.
+
+```SQL
+SELECT * FROM OBS_GetAvailableDenominators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, NULL, 'us.census.tiger.state')
+WHERE valid_geom IS True;
+```
+
+- Obtain all denominators available in the timespan `2011 - 2015`.
+
+```SQL
+SELECT * FROM OBS_GetAvailableDenominators(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, NULL, NULL, '2011 - 2015')
+WHERE valid_timespan IS True;
+```
+
+- Obtain all geometries that are available within a small rectangle.
+
+```SQL
+SELECT * FROM OBS_GetAvailableGeometries(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326));
+```
+
+- Obtain all geometries that are available within a small rectangle and are for
+the United States only.
+
+```SQL
+SELECT * FROM OBS_GetAvailableGeometries(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), '{section/tags.united_states}');
+```
+
+- Obtain all geometries that work with total population (`us.census.acs.B01003001`).
+
+```SQL
+SELECT * FROM OBS_GetAvailableGeometries(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, 'us.census.acs.B01003001')
+WHERE valid_numer IS True;
+```
+
+- Obtain all geometries with timespan  `2015`.
+
+```SQL
+SELECT * FROM OBS_GetAvailableGeometries(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, NULL, NULL, '2015')
+WHERE valid_timespan IS True;
+```
+
+- Obtain all timespans that are available within a small rectangle.
+
+```SQL
+SELECT * FROM OBS_GetAvailableTimespans(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326));
+```
+
+- Obtain all timespans for total population (`us.census.acs.B01003001`).
+
+```SQL
+SELECT * FROM OBS_GetAvailableTimespans(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, 'us.census.acs.B01003001')
+WHERE valid_numer IS True;
+```
+
+- Obtain all timespans that work with US states (`us.census.tiger.state`)
+as a geometry.
+
+```SQL
+SELECT * FROM OBS_GetAvailableTimespans(
+  ST_MakeEnvelope(-74, 41, -73, 40, 4326), NULL, NULL, NULL, 'us.census.tiger.state')
+WHERE valid_geom IS True;
+```