Типы факторов¶

Circle¶

Агрегирует датасет в радиусе вокруг точки.

type: 'circle'
dataset: str, агрегируемый датасет
filter: dict = None, фильтр датасета в формате mongo
field: str, агрегируемое поле датасета или формула numexpr
agg: str, функция агрегации
limit: int, радиус круга, то есть максимальное расстояние в метрах до точек датасета
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None
metric_funcs: List[dict] = [], метрические функции
geometry: Optional[Literal['geopos', 'geometry']] = None, поле геометрии датасета; если None, будет выбрано 'geopos' при его наличии, иначе 'geometry'

Пример конфига:

circle_feature = {
    'type': 'circle',
    'dataset': 'ru-pub-households/apartments',
    'field': 'apartments',
    'limit': 300,
    'agg': 'sum',
    'fillna': 0,
    'filter': {'price': {'$lt': 145000.0}},
}

Isochrone¶

Агрегирует датасет внутри изохроны вокруг точки.

type: 'isochrone'
dataset: str, агрегируемый датасет
filter: dict = None, фильтр датасета в формате mongo
metric: str, метрика роутера
field: str, агрегируемое поле датасета или формула numexpr
agg: str, функция агрегации
limit: int, радиус изохроны, то есть максимальное время в пути или расстояние до точек датасета
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None
metric_funcs: List[dict] = [], метрические функции
geometry: Optional[Literal['geopos', 'geometry']] = None, поле геометрии датасета; если None, будет выбрано 'geopos' при его наличии, иначе 'geometry'

Пример конфига:

isochrone_feature = {
    'type': 'isochrone',
    'dataset': 'ru-pub-households/apartments',
    'field': 'apartments',
    'metric': 'foot',
    'limit': 5,
    'agg': 'sum',
    'fillna': 0,
}

Huff¶

Агрегирует датасет, используя вероятностные веса из модели Хаффа, то есть с учётом конкурентов.

Пример:

Допустим, мы считаем сумму квартир с учётом конкурентов, и у нашего магазина есть один конкурент. Влияние каждого из них на каждый дом можно посчитать по формуле \(\frac{weight}{metric}\) (строки конкурента выделены красным):

house id	apartments	point id	point metric	point weight	influence
1	100	1	8	1000	125
1	100	2	4	2000	500
2	120	1	5	1000	200
2	120	2	10	2000	200
3	150	1	1	1000	1000
3	150	2	8	2000	250

Затем вероятность для каждого дома считается как \(p_i = \frac{infl_i}{\sum_i infl_i}\):

house id	apartments	point id	influence	probability
1	100	1	125	0.2
1	100	2	500	0.8
2	120	1	200	0.5
2	120	2	200	0.5
3	150	1	1000	0.8
3	150	2	250	0.2

А результат агрегации — \(0.2 * 100 + 0.5 * 120 + 0.8 * 150 = 200\)

type: 'huff'
dataset: str, агрегируемый датасет
filter: dict = None, фильтр датасета в формате mongo
metric: str, расстояние или метрика роутера
weight: Optional[str] = None, имя веса без префикса wt:
field: str, агрегируемое поле датасета или формула numexpr
agg: str, функция агрегации
limit: int, ограничение метрики, то есть максимальное время в пути или расстояние до точек датасета
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None
metric_funcs: List[dict] = [], метрические функции
infl_func: Optional[dict] = None, функция влияния
winner_takes_all: bool = False, если True, вероятностный вес будет равен 1 для точки с наибольшим влиянием, то есть победитель по влиянию «забирает всё»
cannibalization: bool = True, если False, набор точек не считается конкурентами для текущих точек. Точки не являются конкурентами сами себе
geometry: Optional[Literal['geopos', 'geometry']] = None, поле геометрии датасета; если None, будет выбрано 'geopos' при его наличии, иначе 'geometry'
competitors_filter: Optional[dict] = None, фильтр датасета конкурентов в формате mongo

Для рассчитываемой точки конкурентами будут считаться точки из competitors и остальные точки из points (см. конфиг FAAS).

Пример конфига:

huff_feature = {
    'type': 'huff',
    'dataset': 'ru-pub-households/apartments',
    'field': 'apartments',
    'metric': 'foot',
    'limit': 10,
    'agg': 'sum',
    'fillna': 0,
}

Distance¶

Считает расстояние или метрику роутера до ближайшего по этой метрике элемента датасета.

type: 'distance'
dataset: str
filter: dict = None, фильтр датасета в формате mongo
metric: str, расстояние или метрика роутера
limit: int, ограничение метрики, то есть максимальное время в пути или расстояние до точек датасета
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None
rank: int = 1, ранг близости. 1 означает расстояние до ближайшего элемента датасета, 2 — до второго по близости и так далее.
metric_funcs: List[dict] = [], метрические функции (поддерживаются только circle и donut)
geometry: Optional[Literal['geopos', 'geometry']] = None, поле геометрии датасета; если None, будет выбрано 'geopos' при его наличии, иначе 'geometry'

Пример конфига:

distance_feature = {
    'type': 'distance',
    'dataset': 'ru-pub-households/apartments',
    'metric': 'dist',
    'limit': 500,
    'fillna': -1,
    'rank': 1,
}

Near¶

Берёт поле из ближайшего по расстоянию или метрике роутера элемента датасета.

type: 'near'
dataset: str
filter: dict = None, фильтр датасета в формате mongo
field: str, агрегируемое поле датасета
metric: str, расстояние или метрика роутера
limit: int, ограничение метрики, то есть максимальное время в пути или расстояние до точек датасета
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None
dropna: bool = False, выбрасывать ли пустые поля (None, NaN)
dropzero: bool = False, выбрасывать ли поля с нулевым значением
rank: int = 1, ранг близости. 1 означает расстояние до ближайшего элемента датасета, 2 — до второго по близости и так далее.
metric_funcs: List[dict] = [], метрические функции (поддерживаются только circle и donut)
geometry: Optional[Literal['geopos', 'geometry']] = None, поле геометрии датасета; если None, будет выбрано 'geopos' при его наличии, иначе 'geometry'
geometry_filter: Optional[str] = None, фильтры геометрии

Пример конфига:

near_feature = {
    'type': 'near',
    'dataset': 'ru-pub-households/apartments',
    'field': 'apartments',
    'metric': 'dist',
    'limit': 300,
    'fillna': 0,
    'dropna': True,
    'dropzero': True,
    'rank': 2,
}

Match¶

Берёт поле из элемента датасета, который пересекается с точкой по геометрии. Элементы датасета должны содержать geojson-полигоны в поле geometry.

type: 'match'
dataset: str, датасет с полигонами
filter: dict = None, фильтр датасета в формате mongo
field: str, поле датасета
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None

Пример конфига:

match_feature = {
    'type': 'match',
    'dataset': 'ru-pub-polygons/regions',
    'field': 'name',
    'fillna': 0,
}

Match_aggregate¶

Берёт полигон из одного датасета и агрегирует внутри этого полигона другой датасет. Полигон может сопоставляться с точкой по пересечению геометрий или по полю id.

Элементы датасета с полигонами должны содержать geojson-полигоны в поле geometry.

type: 'match_aggregate'
dataset: str, датасет с полигонами
filter: dict = None, фильтр датасета с полигонами в формате mongo
agg: dict, правило агрегации
by: str = 'geometry', если 'geometry' — сопоставление по пересечению геометрий, если 'id' — сопоставление по полю id
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None

где правило агрегации — это:

dataset: str, агрегируемый датасет
filter: dict = None, фильтр агрегируемого датасета в формате mongo
field: str, агрегируемое поле датасета или формула numexpr
agg: str, функция агрегации

Пример конфига:

match_aggregate_feature = {
    'type': 'match_aggregate',
    'dataset': 'ru-pub-polygons/regions',
    'agg': {
        'dataset': 'ru-pub-households/apartments',
        'field': 'apartments',
        'agg': 'sum',
    },
    'fillna': 0,
}

Collect¶

Операция «сбора» факторов со связанных точек.

Предположим, что для каждой точки в dataset есть набор точек, связанных по некоторому id. Для каждой такой точки мы считаем feature, а затем агрегируем получившиеся факторы с заданным весом.

type: 'collect'
dataset: str, датасет связанных точек
feature: dict, конфиг фактора, который считается для каждой точки из dataset. Должен быть одним из Circle, Isochrone, Distance, Near
weight: str = 'none', имя веса без префикса wt:
agg: str, функция агрегации
id_field: str = 'id', имя поля id в датасете точек
fillna: Optional[float] = None, значение, возвращаемое вместо NaN/None

Пример конфига:

collect_feature = {
    'type': 'collect',
    'dataset': 'client/traffic_probability',
    'agg': 'sum',
    'fillna': 0,
    'feature': {
        'type': 'circle',
        'limit': 1500,
        'dataset': 'ru-pub-households/apartments',
        'field': 'price',
        'agg': 'sum',
        'fillna': 0,
    },
}

Если вы хотите передать собираемые точки явно, задайте поле collect:{сюда нужно подставить имя датасета collect-фактора} со значением list[dict]. Например:

config = {
    'points': [
        {
            'id': 1,
            'geopos': {'type': 'Point', 'coordinates': [33, 55]},
            'collect:client/traffic_probability': [
                {
                    'id': 125,
                    'geopos': {'type': 'Point', 'coordinates': [33.5, 55.5]},
                },
                {
                    'id': 127,
                    'geopos': {'type': 'Point', 'coordinates': [33.7, 55.7]},
                },
            ],
        }
    ],
    'features': {
        'type': 'collect',
        'dataset': 'client/traffic_probability',
        ...,
    },
}

Более сложный пример с АЗС:

Агрегация трафика с разных въездов

С каждой АЗС связан набор точек, задающих её въезды. Для каждого въезда указан коэффициент конверсии трафика wt:conv. Кроме того, поле id_gas_station в каждом въезде указывает на id соответствующей АЗС.

Датасет въездов traffic_points (точки) содержит поля id_azs, geopos и wt:conv.

Датасет traffic (линии) содержит поля intensity и geometry.

collect_feature = {
    'type': 'collect',
    'dataset': 'client/traffic_points',
    'id_field': 'id_gas_station',
    'agg': 'sum',
    'weight': 'conv',
    'feature': {
        'type': 'near',
        'dataset': 'client/traffic',
        'field': 'intensity',
        'metric': 'dist',
        'limit': 30,
        'geometry_filter': 'cross_right',
        'dropna': True,
        'dropzero': True,
        'fillna': 0,
    },
}

Вложенный Near фактор означает «взять ближайшую интенсивность трафика на той стороне дороги, где находится точка въезда».