filling the gaps

doc/07_gravity.md

@@ -1,40 +1,64 @@
-## Gravity Model 
+## Gravity Model
 
-### CDB_Gravity()
+### CDB_Gravity(t_id bigint[], t_geom geometry[], t_weight numeric[], s_id bigint[], s_geom geometry[], s_pop numeric[], target bigint, radius integer, minval numeric DEFAULT -10e307)
 
-The Gravity Model is derived from newtons law of gravity and is used to estimate the degree of interaction between two places 
+Gravity Models are derived from Newton's Law of Gravity and are used to predict the interaction between a group of populated areas (sources) and a specific target among a group of potential targets, in terms of an attraction factor (weight)
 
-#### Arguments 
+**CDB_Gravity** is based on the model defined in *Huff's Law of Shopper attraction (1963)*
 
-| Name | Type | Description | 
+#### Arguments
+
+| Name | Type | Description |
 |------|------|-------------|
-| t_id     | bigint[]    |     |
-| t_geom   | geometry[]  |     |
-| t_weight | numeric[]   |     |
-| s_id     | bigint[]    |     |
-| s_geom   | geometry[]  |     |
-| s_pop    | numeric[]   |     |
-| target   | bigint      |     |
-| radius   | integer     |     |
-| minval   | numeric     |     |
+| t_id     | bigint[]    | Array of targets ID |
+| t_geom   | geometry[]  | Array of targets' geometries |
+| t_weight | numeric[]   | Array of targets's weights |
+| s_id     | bigint[]    | Array of sources ID |
+| s_geom   | geometry[]  | Array of sources' geometries |
+| s_pop    | numeric[]   | Array of sources's population |
+| target   | bigint      | ID of the target under study |
+| radius   | integer     | Radius in meters around the target under study that will be taken into account|
+| minval (optional)   | numeric     | Lowest accepted value of weight, defaults to numeric min_value |
 
 
-#### Returns 
+#### Returns
 
 | Column Name | Type | Description |
 |-------------|------|-------------|
-| the_geom  | Numeric | |
-| source_id | bigint  | |
-| target_id | bigint  | |
-| dist      | Numeric | |
-| n         | Numeric | |
-| hpop      | NUMERIC | |
+| the_geom  | geometry | Geometries of the sources within the radius |
+| source_id | bigint  | ID of the source |
+| target_id | bigint  | Target ID from input |
+| dist      | numeric | Distance in meters source to target (if not points, distance between centroids) |
+| h         | numeric | Probability of patronage |
+| hpop      | numeric | Patronaging population |
 
 
 #### Example Usage
 
 ```sql
-SELECT CDB_GRAVITY ();
+with t as (
+SELECT
+    array_agg(cartodb_id::bigint) as id,
+    array_agg(the_geom) as g,
+    array_agg(coalesce(gla,0)::numeric) as w
+FROM
+    abel.centros_comerciales_de_madrid
+WHERE not no_cc
+),
+s as (
+SELECT
+    array_agg(cartodb_id::bigint) as id,
+    array_agg(center) as g,
+    array_agg(coalesce(t1_1, 0)::numeric) as p
+FROM
+    sscc_madrid
+)
+select
+    g.the_geom,
+    trunc(g.h,2) as h,
+    round(g.hpop) as hpop,
+    trunc(g.dist/1000,2) as dist_km
+FROM t, s, CDB_Gravity1(t.id, t.g, t.w, s.id, s.g, s.p, newmall_ID, 100000, 5000) g
 ```
 
 

src/pg/test/expected/07_gravity_test.out

@@ -0,0 +1,11 @@
+                  the_geom                  |            h            |           hpop           |      dist
+--------------------------------------------+-------------------------+--------------------------+----------------
+ 01010000001361C3D32B650140DD24068195B34440 |  1.51078258369747945249 |  12.08626066957983561994 | 4964.714459152
+ 01010000002497FF907EFB0040713D0AD7A3B04440 | 98.29730954183620807430 | 688.08116679285345652007 |   99.955141922
+ 0101000000A167B3EA733501401D5A643BDFAF4440 | 63.70532894711274639196 | 382.23197368267647835174 | 2488.330566505
+ 010100000062A1D634EF380140BE9F1A2FDDB44440 | 35.35415870080995954879 | 176.77079350404979774397 | 4359.370460594
+ 010100000052B81E85EB510140355EBA490CB24440 | 33.12290506987740864904 | 132.49162027950963459615 | 3703.664449828
+ 0101000000C286A757CA320140736891ED7CAF4440 | 65.45251754279248087849 | 196.35755262837744263547 | 2512.092358644
+ 01010000007DD0B359F5390140C976BE9F1AAF4440 | 62.83927792471345639225 | 125.67855584942691278449 |  2926.25725244
+ 0101000000D237691A140D01407E6FD39FFDB44440 | 53.54905726651871279586 |  53.54905726651871279586 | 3744.515577777
+(8 rows)

src/pg/test/sql/07_gravity_test.sql

@@ -1 +1,21 @@
-select * form CDB_Gravity()
+WITH t AS (
+    SELECT
+    ARRAY[1,2,3] AS id,
+    ARRAY[7.0,8.0,3.0] AS w,
+    ARRAY[ST_GeomFromText('POINT(2.1744 41.4036)'),ST_GeomFromText('POINT(2.1228 41.3809)'),ST_GeomFromText('POINT(2.1511 41.3742)')] AS g
+),
+s AS (
+    SELECT
+    ARRAY[10,20,30,40,50,60,70,80] AS id,
+    ARRAY[800, 700, 600, 500, 400, 300, 200, 100] AS p,
+    ARRAY[ST_GeomFromText('POINT(2.1744 41.403)'),ST_GeomFromText('POINT(2.1228 41.380)'),ST_GeomFromText('POINT(2.1511 41.374)'),ST_GeomFromText('POINT(2.1528 41.413)'),ST_GeomFromText('POINT(2.165 41.391)'),ST_GeomFromText('POINT(2.1498 41.371)'),ST_GeomFromText('POINT(2.1533 41.368)'),ST_GeomFromText('POINT(2.131386 41.41399)')] AS g
+)
+SELECT
+    g.the_geom,
+    g.h,
+    g.hpop,
+    g.dist
+FROM
+    t,
+    s,
+    CDB_Gravity(t.id, t.g, t.w, s.id, s.g, s.p, 2, 100000, 3) g;