Faas config

Config schema:

config = {
    'points': str | [],
    'competitors': str | [],
    'features': {str: feature},
    'precision': int,
    'infl_limits': {str: float},
    'region': str,
}

Points

The points can be either a list of dicts, or a dataset that contains a set of points. For a large number of points, it is recommended to use a dataset.

Point fields:

id

int, each point must have a unique id;

geopos

dict, point geometry in geojson format;

wt:*

float, point can have different weights (used in huff features). Each weight field must start with wt:.

collect:*

list[dict], Optional lists of points for collect features (see more in collect feature).

Example:

{
    'id': 1,
    'geopos': {'type': 'Point', 'coordinates': [30.32, 60.07]},
    'wt:area': 0.9,
    'wt:none': 1.0,
}

Competitors

competitors is an optional field that is used in huff features. It contains points (as a list of dicts or as a dataset) that must be taken into account only as competitors, so features are not calculated for them. The competitors point fields are the same as points point fields.

Features

features is a required field, dictionary {str: feature}, where str is the name of the feature to be set, and feature is the feature config. Go to the feature types section for a detailed description of available features.

Precision

precision is an optional field that indicates the accuracy of calculating the router metrics. The higher the precision, the more accurate is the calculation, but it might take considerably longer if you calculate a lot of features. Values higher than 22 or lower than 15 should not be used; the default value (19) is usually sufficient.

What is a geofield?

Calculating the time between two points using a router (a metric other than dist) is a rather expensive operation and the calculated time may not always directly affect the result. For example, for large hypermarkets without competition, for which people will be ready to travel from far away - there is no need to calculate the distances from each apartment to the store - the impact will be minimal, and the calculation time is huge. Instead, you can reduce the accuracy of calculations and increase the coverage radius. On the other hand, in densely populated urban areas where coffee shops are located every 100 meters, high calculation accuracy is needed. Every minute is already important here, and a margin of error of a few minutes can make a difference.

To optimize the process of calculating travel time, we can use a geofield.

A geofield is a special regular grid overlaid on a map that allows you to pre-calculate the time from a source point to the centers of the cells containing destination points, in order to reuse the automobile and pedestrian router calculations on different datasets.

The grid precision determines the size of the cell by dividing the equator into \(2^{precision}\) equal parts. The higher the precision, the smaller the cell size.

Thus the mechanism is as follows:

1. Get source point and destination point for time calculation
2. Determine which cell contains the destination point
3. Determine the center of that cell
4. Calculate the router time between the original source point and the center of the destination point's cell
5. Cache (store in memory) the time for this source-point and destination-cell pair
6. The next time a destination point is in the same cell and the source point is the same, the time can be retrieved from the cache instead of calculated again

precision	cell size
15	1.2 km
16	611 m
17	306 m
18	153 m
19	76 m
20	38 m
21	19 m
22	9 m

Infl_limits

infl_limits is an optional dict of pairs {metric: limit} that is used in huff features. It specifies "circle of influence" of each point, i.e. the points at the distance >= 2 * limit meters are not considered competitors. Normally you don't have to set this field.

Region

region is an optional field that specifies router region. Some metrics can only be used in a specific region. Default is cis.

Full example

config = {
    'points': 'client/points',
    'competitors': 'client/competitors',
    'precision': 19,
    'infl_limits': {'foot': 1000, 'car_in': 20000},
    'region': 'cis',
    'features': {
        'price_avg_r1000': {
            'type': 'circle',
            'dataset': 'ru-pub-households/apartments',
            'agg': 'mean',
            'field': 'price',
            'limit': 1000,
        },
        'metro_distance': {
            'type': 'distance',
            'dataset': 'ru-pub-transport/metro',
            'metric': 'foot',
            'limit': 30,
        },
        'new_buildings_huff_f10': {
            'type': 'huff',
            'dataset': 'ru-pub-households/new_buildings',
            'agg': 'sum',
            'field': 'apartments',
            'fillna': 0,
            'limit': 10,
            'metric': 'foot',
        },
    },
}