flowclient.aggregates¶

active_at_reference_location_counts¶

active_at_reference_location_counts(*, connection: flowclient.connection.Connection, reference_locations: Dict[str, Union[str, Dict[str, str]]], unique_locations: Dict[str, Union[str, Dict[str, str]]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

A count by location of subscribers who were active in their reference location.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
reference_locations: typing.Dict

Modal or daily location
unique_locations: typing.Dict

unique locations

Returns¶

flowclient.api_query.APIQuery

active_at_reference_location_counts query

active_at_reference_location_counts_spec¶

active_at_reference_location_counts_spec(*, reference_locations: Dict[str, Union[str, Dict[str, str]]], unique_locations: Dict[str, Union[str, Dict[str, str]]]) -> Dict[str, Union[str, Dict[str, str]]]

Source: flowclient/aggregates.py

A count by location of subscribers who were active in their reference location.

Parameters¶

reference_locations: typing.Dict

Modal or daily location
unique_locations: typing.Dict

unique locations

Returns¶

typing.Dict

Query specification

aggregate_network_objects¶

aggregate_network_objects(*, connection: flowclient.connection.Connection, total_network_objects: Dict[str, str], statistic: str, aggregate_by: str) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return aggregate network objects query

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
total_network_objects: typing.Dict

Query spec produced by total_network_objects
statistic: str

Statistic type one of "avg", "max", "min", "median", "mode", "stddev" or "variance".
aggregate_by: str

Period type one of "second", "minute", "hour", "day", "month", "year" or "century".

Returns¶

flowclient.api_query.APIQuery

Aggregate network objects query

aggregate_network_objects_spec¶

aggregate_network_objects_spec(*, total_network_objects: Dict[str, str], statistic: str, aggregate_by: str = 'day') -> dict

Source: flowclient/aggregates.py

Return query spec for aggregate network objects

Parameters¶

total_network_objects: typing.Dict

Query spec produced by total_network_objects
statistic: str

Statistic type one of "avg", "max", "min", "median", "mode", "stddev" or "variance".
aggregate_by: str, default day

Period type one of "second", "minute", "hour", "day", "month", "year" or "century".

Returns¶

dict

Query specification for an aggregated network objects query

calendar_activity¶

calendar_activity(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, count_interval: str, direction: str, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return an aggregation of calendar activity patterns, optionally grouped spatially. This query returns an array of datetimes, and a count of the number of subscribers who had an activity pattern which matched that sequence of datetimes.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
count_interval: str

Can be one of "day", "hour" or "minute".
direction: str

Optionally, include only ingoing or outbound calls/texts. Can be one of "in", "out" or "both".
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to include in event counts. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional

Hours of the day to include

Returns¶

flowclient.api_query.APIQuery

Calendar activity query

calendar_activity_spec¶

calendar_activity_spec(*, start_date: str, total_periods: int, period_unit: str = 'days', period_length: int = 1, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict

Source: flowclient/aggregates.py

Return query spec for total active periods.

Parameters¶

start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
total_periods: int

Total number of periods to break your time span into
period_length: int, default 1

Total number of days per period.
period_unit: str, default days

Split this time frame into hours or days etc.
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to include in event counts. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional, default None

Hours of the day to include

Returns¶

dict

Dict which functions as the query specification

consecutive_trips_od_matrix¶

consecutive_trips_od_matrix(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Retrieves the count of subscriber who made consecutive visits between locations

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str
end_date: str

ISO format dates between which to find trips, e.g. "2016-01-01"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve trips for. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional

Hours of the day to include

Returns¶

flowclient.api_query.APIQuery

consecutive_trips_od_matrix query

consecutive_trips_od_matrix_spec¶

consecutive_trips_od_matrix_spec(*, start_date: str, end_date: str, aggregation_unit: str, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None, hours: Optional[Tuple[int, int]] = None) -> Dict[str, Union[str, Dict[str, str]]]

Source: flowclient/aggregates.py

Retrieves the count of subscriber who made consecutive visits between locations

Parameters¶

start_date: str
end_date: str

ISO format dates between which to find trips, e.g. "2016-01-01"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve trips for. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional, default None

Hours of the day to include

Returns¶

typing.Dict

Consecutive trips od matrix query specification.

flows¶

flows(*, connection: flowclient.connection.Connection, from_location: Dict[str, Union[str, Dict[str, str]]], to_location: Dict[str, Union[str, Dict[str, str]]], join_type: str) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Flows between two locations.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
from_location: typing.Dict

Query which maps individuals to single location for the "origin" period of interest.
to_location: typing.Dict

Query which maps individuals to single location for the "destination" period of interest.
join_type: str

Join type to use to build the flows

Returns¶

flowclient.api_query.APIQuery

Flows query

flows_spec¶

flows_spec(*, from_location: Dict[str, Union[str, Dict[str, str]]], to_location: Dict[str, Union[str, Dict[str, str]]], join_type: str = 'inner') -> dict

Source: flowclient/aggregates.py

Return query spec for flows between two locations.

Parameters¶

from_location: typing.Dict

Query which maps individuals to single location for the "origin" period of interest.
to_location: typing.Dict

Query which maps individuals to single location for the "destination" period of interest.
join_type: str, default inner

Join type to use to build the flows

Returns¶

dict

Dict which functions as the query specification for the flow

histogram_aggregate¶

histogram_aggregate(*, connection: flowclient.connection.Connection, metric: Dict[str, Union[str, Dict[str, str]]], bins: Union[int, List[float]], range: Optional[Tuple[float, float]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return a query spec for a metric aggregated as a histogram.

Parameters¶

metric: typing.Dict

Metric to calculate and aggregate
bins: typing.Union

Either an integer number of bins for equally spaced bins, or a list of floats giving the lower and upper edges
range: typing.Optional

Optionally supply inclusive lower and upper bounds to build the histogram over. By default, the histogram will cover the whole range of the data.

Returns¶

flowclient.api_query.APIQuery

Histogram aggregate query

histogram_aggregate_spec¶

histogram_aggregate_spec(*, metric: Dict[str, Union[str, Dict[str, str]]], bins: Union[int, List[float]], range: Optional[Tuple[float, float]] = None) -> dict

Source: flowclient/aggregates.py

Return a query spec for a metric aggregated as a histogram.

Parameters¶

metric: typing.Dict

Metric to calculate and aggregate
bins: typing.Union

Either an integer number of bins for equally spaced bins, or a list of floats giving the lower and upper edges
range: typing.Optional, default None

Optionally supply inclusive lower and upper bounds to build the histogram over. By default, the histogram will cover the whole range of the data.

Returns¶

dict

Query specification for histogram aggregate over a metric

inflows¶

inflows(*, connection: flowclient.connection.Connection, from_location: Dict[str, Union[str, Dict[str, str]]], to_location: Dict[str, Union[str, Dict[str, str]]], join_type: str) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Given a set of from- and to- locations, returns a count of every user that travelled to each destination location.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
from_location: typing.Dict

Query which maps individuals to single location for the "origin" period of interest.
to_location: typing.Dict

Query which maps individuals to single location for the "destination" period of interest.
join_type: str

Join type to use to build the flows

Returns¶

flowclient.api_query.APIQuery

Inflows query

inflows_spec¶

inflows_spec(*, from_location: Dict[str, Union[str, Dict[str, str]]], to_location: Dict[str, Union[str, Dict[str, str]]], join_type: str = 'inner') -> dict

Source: flowclient/aggregates.py

joined_spatial_aggregate¶

joined_spatial_aggregate(*, connection: flowclient.connection.Connection, locations: Dict[str, Union[str, Dict[str, str]]], metric: Dict[str, Union[str, Dict[str, str]]], method: str) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Query for a metric aggregated by attaching location information.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
locations: typing.Dict

Modal or daily location query to use to localise the metric
metric: typing.Dict

Metric to calculate and aggregate
method: str

Method of aggregation; one of "avg", "max", "min", "median", "mode", "stddev", "variance" or "distr". If the metric refers to a categorical variable (e.g. a subscriber handset type) it will only accept the "distr" method which yields the relative distribution of possible values. All of the other methods will be rejected. On the other hand, the "distr" method will be rejected for all continuous variables.

Returns¶

flowclient.api_query.APIQuery

Joined spatial aggregate query

joined_spatial_aggregate_spec¶

joined_spatial_aggregate_spec(*, locations: Dict[str, Union[str, Dict[str, str]]], metric: Dict[str, Union[str, Dict[str, str]]], method: str = 'avg') -> dict

Source: flowclient/aggregates.py

Return a query spec for a metric aggregated by attaching location information.

Parameters¶

locations: typing.Dict

Modal or daily location query to use to localise the metric
metric: typing.Dict

Metric to calculate and aggregate
method: str, default avg

Method of aggregation; one of "avg", "max", "min", "median", "mode", "stddev", "variance" or "distr". If the metric refers to a categorical variable (e.g. a subscriber handset type) it will only accept the "distr" method which yields the relative distribution of possible values. All of the other methods will be rejected. On the other hand, the "distr" method will be rejected for all continuous variables.

Returns¶

dict

Query specification for an aggregated daily or modal location

labelled_flows¶

labelled_flows(*, connection: flowclient.connection.Connection, from_location: Dict[str, Any], to_location: Dict[str, Any], labels: Dict[str, Any], join_type: str) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Flows between two locations, disaggregated by labels from a categorical subscriber metric.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
from_location: typing.Dict

Query which maps individuals to single location for the "origin" period of interest.
to_location: typing.Dict

Query which maps individuals to single location for the "destination" period of interest.
labels: typing.Dict

Categorical subscriber metric query whose values will be used to disaggregate the subscriber counts.
join_type: str

Join type to use to build the flows

Returns¶

flowclient.api_query.APIQuery

Labelled flows query

labelled_flows_spec¶

labelled_flows_spec(*, from_location: Dict[str, Any], to_location: Dict[str, Any], labels: Dict[str, Any], join_type: str = 'inner') -> dict

Source: flowclient/aggregates.py

Return query spec for flows between two locations, disaggregated by labels from a categorical subscriber metric.

Parameters¶

from_location: typing.Dict

Query which maps individuals to single location for the "origin" period of interest.
to_location: typing.Dict

Query which maps individuals to single location for the "destination" period of interest.
labels: typing.Dict

Categorical subscriber metric query whose values will be used to disaggregate the subscriber counts.
join_type: str, default inner

Join type to use to build the flows

Returns¶

dict

Query specification for the labelled flows query

labelled_spatial_aggregate¶

labelled_spatial_aggregate(*, connection: flowclient.connection.Connection, locations: Dict[str, Any], labels: Dict[str, Any]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Retrieves the counts of subscribers per location, disaggregated by labels from a categorical subscriber metric.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
locations: typing.Dict

Location query to aggregate spatially
labels: typing.Dict

Categorical subscriber metric query whose values will be used to disaggregate the subscriber counts

Returns¶

flowclient.api_query.APIQuery

Labelled spatial aggregate query

labelled_spatial_aggregate_spec¶

labelled_spatial_aggregate_spec(*, locations: Dict[str, Any], labels: Dict[str, Any]) -> dict

Source: flowclient/aggregates.py

Retrieves the counts of subscribers per location, disaggregated by labels from a categorical subscriber metric.

Parameters¶

locations: typing.Dict

Location query to aggregate spatially
labels: typing.Dict

Categorical subscriber metric query whose values will be used to disaggregate the subscriber counts

Returns¶

dict

Query specification for a labelled spatial aggregate query

localised_calendar_activity¶

localised_calendar_activity(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, count_interval: str, direction: str, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return an aggregation of calendar activity patterns grouped spatially. This query returns an array of datetimes per spatial unit, and a count of the number of subscribers who had an activity pattern which matched that sequence of datetimes with a reference location matching that spatial unit.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
count_interval: str

Can be one of "day", "hour" or "minute".
direction: str

Optionally, include only ingoing or outbound calls/texts. Can be one of "in", "out" or "both".
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to include in event counts. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional

Hours of the day to include
locations: dict

Modal or daily location query to use to localise the metric

Returns¶

flowclient.api_query.APIQuery

Calendar activity query

localised_calendar_activity_spec¶

localised_calendar_activity_spec(*, start_date: str, total_periods: int, period_unit: str = 'days', period_length: int = 1, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None, locations: Optional[Dict[str, Union[str, Dict[str, str]]]] = None) -> dict

Source: flowclient/aggregates.py

Return query spec for total active periods.

Parameters¶

start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
total_periods: int

Total number of periods to break your time span into
period_length: int, default 1

Total number of days per period.
period_unit: str, default days

Split this time frame into hours or days etc.
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to include in event counts. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional, default None

Hours of the day to include
locations: typing.Optional, default None

Optionally provide modal or daily location query to use to localise the metric

Returns¶

dict

Dict which functions as the query specification

location_event_counts¶

location_event_counts(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, count_interval: str, direction: str, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return a location event counts query aggregated spatially and temporally. Counts are taken over between 00:01 of start_date up until 00:00 of end_date (i.e. exclusive date range).

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
count_interval: str

Can be one of "day", "hour" or "minute".
direction: str

Optionally, include only ingoing or outbound calls/texts. Can be one of "in", "out" or "both".
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to include in event counts. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional

Hours of the day to include

Returns¶

flowclient.api_query.APIQuery

Location event counts query

location_event_counts_spec¶

location_event_counts_spec(*, start_date: str, end_date: str, aggregation_unit: str, count_interval: str, direction: str = 'both', event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None, hours: Optional[Tuple[int, int]] = None) -> dict

Source: flowclient/aggregates.py

Return query spec for a location event counts query aggregated spatially and temporally. Counts are taken over between 00:01 of start_date up until 00:00 of end_date (i.e. exclusive date range).

Parameters¶

start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
count_interval: str

Can be one of "day", "hour" or "minute".
direction: str, default both

Optionally, include only ingoing or outbound calls/texts. Can be one of "in", "out" or "both".
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to include in event counts. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional, default None

Hours of the day to include

Returns¶

dict

Dict which functions as the query specification

location_introversion¶

location_introversion(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, direction: str, mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return location introversion query

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
direction: str

Optionally, include only ingoing or outbound calls/texts can be one of "in", "out" or "both"
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve values for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.
hours: typing.Optional

Hours of the day to include

Returns¶

flowclient.api_query.APIQuery

Location introversion query

location_introversion_spec¶

location_introversion_spec(*, start_date: str, end_date: str, aggregation_unit: str, direction: str = 'both', mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict

Source: flowclient/aggregates.py

Return query spec for location introversion

Parameters¶

start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
direction: str, default both

Optionally, include only ingoing or outbound calls/texts can be one of "in", "out" or "both"
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve values for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.
hours: typing.Optional, default None

Hours of the day to include

Returns¶

dict

Dict which functions as the query specification

meaningful_locations_aggregate¶

meaningful_locations_aggregate(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, label: str, labels: Dict[str, Dict[str, dict]], tower_day_of_week_scores: Dict[str, float], tower_hour_of_day_scores: List[float], aggregation_unit: str, tower_cluster_radius: float, tower_cluster_call_threshold: int, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return a count of meaningful locations at some unit of spatial aggregation. Generates clusters of towers used by subscribers over the given time period, scores the clusters based on the subscribers' usage patterns over hours of the day and days of the week. Each subscriber then has a number of clusters, each of which has a score for hourly usage, and day of week usage. These clusters are then labelled based on whether they overlap with the regions of that space defined in the labels parameter. Once the clusters are labelled, those clusters which have the label specified are extracted, and then a count of subscribers per aggregation unit is returned, based on whether the spatial position of the cluster overlaps with the aggregation unit. Subscribers are not counted directly, but contribute 1/number_of_clusters to the count of each aggregation unit, for each cluster that lies within that aggregation unit. This methodology is based on work originally by Isaacman et al.¹, and extensions by Zagatti et al².

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date that begins the period, e.g. "2016-01-01"
end_date: str

ISO format date for the day after the final date of the period, e.g. "2016-01-08"
label: str

One of the labels specified in labels, or 'unknown'. Locations with this label are returned.
labels: typing.Dict

A dictionary whose keys are the label names and the values geojson-style shapes, specified hour of day, and day of week score, with hour of day score on the x-axis and day of week score on the y-axis, where all scores are real numbers in the range [-1.0, +1.0]
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
tower_day_of_week_scores: typing.Dict

A dictionary mapping days of the week ("monday", "tuesday" etc.) to numerical scores in the range [-1.0, +1.0]. Each of a subscriber's interactions with a tower is given a score for the day of the week it took place on. For example, passing {"monday":1.0, "tuesday":0, "wednesday":0, "thursday":0, "friday":0, "saturday":0, "sunday":0} would score any interaction taking place on a monday 1, and 0 on all other days. So a subscriber who made two calls on a monday, and received one sms on tuesday, all from the same tower would have a final score of 0.666 for that tower.
tower_hour_of_day_scores: typing.List

A length 24 list containing numerical scores in the range [-1.0, +1.0], where the first entry is midnight. Each of a subscriber's interactions with a tower is given a score for the hour of the day it took place in. For example, if the first entry of this list was 1, and all others were zero, each interaction the subscriber had that used a tower at midnight would receive a score of 1. If the subscriber used a particular tower twice, once at midnight, and once at noon, the final hour score for that tower would be 0.5.
tower_cluster_radius: float

When constructing clusters, towers will be considered for inclusion in a cluster only if they are within this number of km from the current cluster centroid. Hence, large values here will tend to produce clusters containing more towers, and fewer clusters.
tower_cluster_call_threshold: int

Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve modal locations for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.

Returns¶

flowclient.api_query.APIQuery

Meaningful locations aggregate query

Note

Does not return any value below 15.

meaningful_locations_aggregate_spec¶

meaningful_locations_aggregate_spec(*, start_date: str, end_date: str, label: str, labels: Dict[str, Dict[str, dict]], tower_day_of_week_scores: Dict[str, float], tower_hour_of_day_scores: List[float], aggregation_unit: str, tower_cluster_radius: float = 1.0, tower_cluster_call_threshold: int = 0, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None) -> dict

Source: flowclient/aggregates.py

Return a query specification for a count of meaningful locations at some unit of spatial aggregation. Generates clusters of towers used by subscribers over the given time period, scores the clusters based on the subscribers' usage patterns over hours of the day and days of the week. Each subscriber then has a number of clusters, each of which has a score for hourly usage, and day of week usage. These clusters are then labelled based on whether they overlap with the regions of that space defined in the labels parameter. Once the clusters are labelled, those clusters which have the label specified are extracted, and then a count of subscribers per aggregation unit is returned, based on whether the spatial position of the cluster overlaps with the aggregation unit. Subscribers are not counted directly, but contribute 1/number_of_clusters to the count of each aggregation unit, for each cluster that lies within that aggregation unit. This methodology is based on work originally by Isaacman et al.¹, and extensions by Zagatti et al².

Parameters¶

start_date: str

ISO format date that begins the period, e.g. "2016-01-01"
end_date: str

ISO format date for the day after the final date of the period, e.g. "2016-01-08"
label: str

One of the labels specified in labels, or 'unknown'. Locations with this label are returned.
labels: typing.Dict

A dictionary whose keys are the label names and the values geojson-style shapes, specified hour of day, and day of week score, with hour of day score on the x-axis and day of week score on the y-axis, where all scores are real numbers in the range [-1.0, +1.0]
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
tower_day_of_week_scores: typing.Dict

A dictionary mapping days of the week ("monday", "tuesday" etc.) to numerical scores in the range [-1.0, +1.0]. Each of a subscriber's interactions with a tower is given a score for the day of the week it took place on. For example, passing {"monday":1.0, "tuesday":0, "wednesday":0, "thursday":0, "friday":0, "saturday":0, "sunday":0} would score any interaction taking place on a monday 1, and 0 on all other days. So a subscriber who made two calls on a monday, and received one sms on tuesday, all from the same tower would have a final score of 0.666 for that tower.
tower_hour_of_day_scores: typing.List

A length 24 list containing numerical scores in the range [-1.0, +1.0], where the first entry is midnight. Each of a subscriber's interactions with a tower is given a score for the hour of the day it took place in. For example, if the first entry of this list was 1, and all others were zero, each interaction the subscriber had that used a tower at midnight would receive a score of 1. If the subscriber used a particular tower twice, once at midnight, and once at noon, the final hour score for that tower would be 0.5.
tower_cluster_radius: float, default 1.0

When constructing clusters, towers will be considered for inclusion in a cluster only if they are within this number of km from the current cluster centroid. Hence, large values here will tend to produce clusters containing more towers, and fewer clusters.
tower_cluster_call_threshold: int, default 0

Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve modal locations for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.

Returns¶

dict

Dict which functions as the query specification

Note

Does not return any value below 15.

meaningful_locations_between_dates_od_matrix¶

meaningful_locations_between_dates_od_matrix(*, connection: flowclient.connection.Connection, start_date_a: str, end_date_a: str, start_date_b: str, end_date_b: str, label: str, labels: Dict[str, Dict[str, dict]], tower_day_of_week_scores: Dict[str, float], tower_hour_of_day_scores: List[float], aggregation_unit: str, tower_cluster_radius: float, tower_cluster_call_threshold: float, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return an origin-destination matrix between one meaningful location in two time periods at some unit of spatial aggregation. This is analagous to performing a flows calculation. Generates clusters of towers used by subscribers' over the given time period, scores the clusters based on the subscribers' usage patterns over hours of the day and days of the week. Each subscriber then has a number of clusters, each of which has a score for hourly usage, and day of week usage. These clusters are then labelled based on whether they overlap with the regions of that space defined in the labels parameter. Once the clusters are labelled, those clusters which have a label of label are extracted, and then a count of of number of subscribers who's labelled clusters have moved between time periods is returned, after aggregating spatially. Each subscriber contributes to 1/(num_cluster_with_label_in_period_a*num_clusters_with_label_in_period_b) to the count. So, for example a subscriber with two clusters labelled evening in the first time period, and only one in the second time period, with all clusters in different spatial units, would contribute 0.5 to the flow from the spatial units holding both the original clusters, to the spatial unit of the cluster in the second time period. This methodology is based on work originally by Isaacman et al.¹, and extensions by Zagatti et al².

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date_a: str
start_date_b: str

ISO format date that begins the period, e.g. "2016-01-01"
end_date_a: str
end_date_b: str

ISO format date for the day after the final date of the period, e.g. "2016-01-08"
label: str

One of the labels specified in labels, or 'unknown'. Locations with this label are returned.
labels: typing.Dict

A dictionary whose keys are the label names and the values geojson-style shapes, specified hour of day, and day of week score, with hour of day score on the x-axis and day of week score on the y-axis, where all scores are real numbers in the range [-1.0, +1.0]
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
tower_day_of_week_scores: typing.Dict

A dictionary mapping days of the week ("monday", "tuesday" etc.) to numerical scores in the range [-1.0, +1.0]. Each of a subscriber's interactions with a tower is given a score for the day of the week it took place on. For example, passing {"monday":1.0, "tuesday":0, "wednesday":0, "thursday":0, "friday":0, "saturday":0, "sunday":0} would score any interaction taking place on a monday 1, and 0 on all other days. So a subscriber who made two calls on a monday, and received one sms on tuesday, all from the same tower would have a final score of 0.666 for that tower.
tower_hour_of_day_scores: typing.List

A length 24 list containing numerical scores in the range [-1.0, +1.0], where the first entry is midnight. Each of a subscriber's interactions with a tower is given a score for the hour of the day it took place in. For example, if the first entry of this list was 1, and all others were zero, each interaction the subscriber had that used a tower at midnight would receive a score of 1. If the subscriber used a particular tower twice, once at midnight, and once at noon, the final hour score for that tower would be 0.5.
tower_cluster_radius: float

When constructing clusters, towers will be considered for inclusion in a cluster only if they are within this number of km from the current cluster centroid. Hence, large values here will tend to produce clusters containing more towers, and fewer clusters.
tower_cluster_call_threshold: float

Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve values for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.

Returns¶

flowclient.api_query.APIQuery

Meaningful locations between dates OD matrix query

Note

Does not return any value below 15.

meaningful_locations_between_dates_od_matrix_spec¶

meaningful_locations_between_dates_od_matrix_spec(*, start_date_a: str, end_date_a: str, start_date_b: str, end_date_b: str, label: str, labels: Dict[str, Dict[str, dict]], tower_day_of_week_scores: Dict[str, float], tower_hour_of_day_scores: List[float], aggregation_unit: str, tower_cluster_radius: float = 1.0, tower_cluster_call_threshold: float = 0, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None) -> dict

Source: flowclient/aggregates.py

Return a query specification for an origin-destination matrix between one meaningful location in two time periods at some unit of spatial aggregation. This is analagous to performing a flows calculation. Generates clusters of towers used by subscribers' over the given time period, scores the clusters based on the subscribers' usage patterns over hours of the day and days of the week. Each subscriber then has a number of clusters, each of which has a score for hourly usage, and day of week usage. These clusters are then labelled based on whether they overlap with the regions of that space defined in the labels parameter. Once the clusters are labelled, those clusters which have a label of label are extracted, and then a count of of number of subscribers who's labelled clusters have moved between time periods is returned, after aggregating spatially. Each subscriber contributes to 1/(num_cluster_with_label_in_period_a*num_clusters_with_label_in_period_b) to the count. So, for example a subscriber with two clusters labelled evening in the first time period, and only one in the second time period, with all clusters in different spatial units, would contribute 0.5 to the flow from the spatial units holding both the original clusters, to the spatial unit of the cluster in the second time period. This methodology is based on work originally by Isaacman et al.¹, and extensions by Zagatti et al².

Parameters¶

start_date_a: str
start_date_b: str

ISO format date that begins the period, e.g. "2016-01-01"
end_date_a: str
end_date_b: str

ISO format date for the day after the final date of the period, e.g. "2016-01-08"
label: str

One of the labels specified in labels, or 'unknown'. Locations with this label are returned.
labels: typing.Dict

A dictionary whose keys are the label names and the values geojson-style shapes, specified hour of day, and day of week score, with hour of day score on the x-axis and day of week score on the y-axis, where all scores are real numbers in the range [-1.0, +1.0]
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
tower_day_of_week_scores: typing.Dict

A dictionary mapping days of the week ("monday", "tuesday" etc.) to numerical scores in the range [-1.0, +1.0]. Each of a subscriber's interactions with a tower is given a score for the day of the week it took place on. For example, passing {"monday":1.0, "tuesday":0, "wednesday":0, "thursday":0, "friday":0, "saturday":0, "sunday":0} would score any interaction taking place on a monday 1, and 0 on all other days. So a subscriber who made two calls on a monday, and received one sms on tuesday, all from the same tower would have a final score of 0.666 for that tower.
tower_hour_of_day_scores: typing.List

A length 24 list containing numerical scores in the range [-1.0, +1.0], where the first entry is midnight. Each of a subscriber's interactions with a tower is given a score for the hour of the day it took place in. For example, if the first entry of this list was 1, and all others were zero, each interaction the subscriber had that used a tower at midnight would receive a score of 1. If the subscriber used a particular tower twice, once at midnight, and once at noon, the final hour score for that tower would be 0.5.
tower_cluster_radius: float, default 1.0

When constructing clusters, towers will be considered for inclusion in a cluster only if they are within this number of km from the current cluster centroid. Hence, large values here will tend to produce clusters containing more towers, and fewer clusters.
tower_cluster_call_threshold: float, default 0

Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve modal locations for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.

Returns¶

dict

Dict which functions as the query specification

Note

Does not return any value below 15.

meaningful_locations_between_label_od_matrix¶

meaningful_locations_between_label_od_matrix(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, label_a: str, label_b: str, labels: Dict[str, Dict[str, dict]], tower_day_of_week_scores: Dict[str, float], tower_hour_of_day_scores: List[float], aggregation_unit: str, tower_cluster_radius: float, tower_cluster_call_threshold: int, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return an origin-destination matrix between two meaningful locations at some unit of spatial aggregation. Generates clusters of towers used by subscribers' over the given time period, scores the clusters based on the subscribers' usage patterns over hours of the day and days of the week. Each subscriber then has a number of clusters, each of which has a score for hourly usage, and day of week usage. These clusters are then labelled based on whether they overlap with the regions of that space defined in the labels parameter. Once the clusters are labelled, those clusters which have either label_a or label_b are extracted, and then a count of number of subscribers who move between the labels is returned, after aggregating spatially. Each subscriber contributes to 1/(num_cluster_with_label_a*num_clusters_with_label_b) to the count. So, for example a subscriber with two clusters labelled evening, and one labelled day, all in different spatial units would contribute 0.5 to the flow from each of the spatial units containing the evening clusters, to the unit containing the day cluster. This methodology is based on work originally by Isaacman et al.¹, and extensions by Zagatti et al².

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date that begins the period, e.g. "2016-01-01"
end_date: str

ISO format date for the day after the final date of the period, e.g. "2016-01-08"
label_a: str
label_b: str

One of the labels specified in labels, or 'unknown'. Calculates the OD between these two labels.
labels: typing.Dict

A dictionary whose keys are the label names and the values geojson-style shapes, specified hour of day, and day of week score, with hour of day score on the x-axis and day of week score on the y-axis, where all scores are real numbers in the range [-1.0, +1.0]
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
tower_day_of_week_scores: typing.Dict

A dictionary mapping days of the week ("monday", "tuesday" etc.) to numerical scores in the range [-1.0, +1.0]. Each of a subscriber's interactions with a tower is given a score for the day of the week it took place on. For example, passing {"monday":1.0, "tuesday":0, "wednesday":0, "thursday":0, "friday":0, "saturday":0, "sunday":0} would score any interaction taking place on a monday 1, and 0 on all other days. So a subscriber who made two calls on a monday, and received one sms on tuesday, all from the same tower would have a final score of 0.666 for that tower.
tower_hour_of_day_scores: typing.List

A length 24 list containing numerical scores in the range [-1.0, +1.0], where the first entry is midnight. Each of a subscriber's interactions with a tower is given a score for the hour of the day it took place in. For example, if the first entry of this list was 1, and all others were zero, each interaction the subscriber had that used a tower at midnight would receive a score of 1. If the subscriber used a particular tower twice, once at midnight, and once at noon, the final hour score for that tower would be 0.5.
tower_cluster_radius: float

When constructing clusters, towers will be considered for inclusion in a cluster only if they are within this number of km from the current cluster centroid. Hence, large values here will tend to produce clusters containing more towers, and fewer clusters.
tower_cluster_call_threshold: int

Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve modal locations for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.

Returns¶

flowclient.api_query.APIQuery

Meaningful locations between label OD matrix query

Note

Does not return any value below 15.

meaningful_locations_between_label_od_matrix_spec¶

meaningful_locations_between_label_od_matrix_spec(*, start_date: str, end_date: str, label_a: str, label_b: str, labels: Dict[str, Dict[str, dict]], tower_day_of_week_scores: Dict[str, float], tower_hour_of_day_scores: List[float], aggregation_unit: str, tower_cluster_radius: float = 1.0, tower_cluster_call_threshold: int = 0, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None) -> dict

Source: flowclient/aggregates.py

Return a query specification for an origin-destination matrix between two meaningful locations at some unit of spatial aggregation. Generates clusters of towers used by subscribers' over the given time period, scores the clusters based on the subscribers' usage patterns over hours of the day and days of the week. Each subscriber then has a number of clusters, each of which has a score for hourly usage, and day of week usage. These clusters are then labelled based on whether they overlap with the regions of that space defined in the labels parameter. Once the clusters are labelled, those clusters which have either label_a or label_b are extracted, and then a count of number of subscribers who move between the labels is returned, after aggregating spatially. Each subscriber contributes to 1/(num_cluster_with_label_a*num_clusters_with_label_b) to the count. So, for example a subscriber with two clusters labelled evening, and one labelled day, all in different spatial units would contribute 0.5 to the flow from each of the spatial units containing the evening clusters, to the unit containing the day cluster. This methodology is based on work originally by Isaacman et al.¹, and extensions by Zagatti et al².

Parameters¶

start_date: str

ISO format date that begins the period, e.g. "2016-01-01"
end_date: str

ISO format date for the day after the final date of the period, e.g. "2016-01-08"
label_a: str
label_b: str

One of the labels specified in labels, or 'unknown'. Calculates the OD between these two labels.
labels: typing.Dict

A dictionary whose keys are the label names and the values geojson-style shapes, specified hour of day, and day of week score, with hour of day score on the x-axis and day of week score on the y-axis, where all scores are real numbers in the range [-1.0, +1.0]
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
tower_day_of_week_scores: typing.Dict

A dictionary mapping days of the week ("monday", "tuesday" etc.) to numerical scores in the range [-1.0, +1.0]. Each of a subscriber's interactions with a tower is given a score for the day of the week it took place on. For example, passing {"monday":1.0, "tuesday":0, "wednesday":0, "thursday":0, "friday":0, "saturday":0, "sunday":0} would score any interaction taking place on a monday 1, and 0 on all other days. So a subscriber who made two calls on a monday, and received one sms on tuesday, all from the same tower would have a final score of 0.666 for that tower.
tower_hour_of_day_scores: typing.List

A length 24 list containing numerical scores in the range [-1.0, +1.0], where the first entry is midnight. Each of a subscriber's interactions with a tower is given a score for the hour of the day it took place in. For example, if the first entry of this list was 1, and all others were zero, each interaction the subscriber had that used a tower at midnight would receive a score of 1. If the subscriber used a particular tower twice, once at midnight, and once at noon, the final hour score for that tower would be 0.5.
tower_cluster_radius: float, default 1.0

When constructing clusters, towers will be considered for inclusion in a cluster only if they are within this number of km from the current cluster centroid. Hence, large values here will tend to produce clusters containing more towers, and fewer clusters.
tower_cluster_call_threshold: int, default 0

Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve modal locations for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.

Returns¶

dict

Dict which functions as the query specification

Note

Does not return any value below 15.

outflows¶

outflows(*, connection: flowclient.connection.Connection, from_location: Dict[str, Union[str, Dict[str, str]]], to_location: Dict[str, Union[str, Dict[str, str]]], join_type: str) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Given a set of from- and to- locations, returns a count of every user that travelled from each origin location.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
from_location: typing.Dict

Query which maps individuals to single location for the "origin" period of interest.
to_location: typing.Dict

Query which maps individuals to single location for the "destination" period of interest.
join_type: str

Join type to use to build the flows

Returns¶

flowclient.api_query.APIQuery

Outflows query

outflows_spec¶

outflows_spec(*, from_location: Dict[str, Union[str, Dict[str, str]]], to_location: Dict[str, Union[str, Dict[str, str]]], join_type: str = 'inner') -> dict

Source: flowclient/aggregates.py

spatial_aggregate¶

spatial_aggregate(*, connection: flowclient.connection.Connection, locations: Dict[str, Union[str, Dict[str, str]]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Spatially aggregated modal or daily location.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
locations: typing.Dict

Modal or daily location query to aggregate spatially

Returns¶

flowclient.api_query.APIQuery

Spatial aggregate query

spatial_aggregate_spec¶

spatial_aggregate_spec(*, locations: Dict[str, Union[str, Dict[str, str]]]) -> dict

Source: flowclient/aggregates.py

Return a query spec for a spatially aggregated modal or daily location.

Parameters¶

locations: typing.Dict

Modal or daily location query to aggregate spatially

Returns¶

dict

Query specification for an aggregated daily or modal location

total_network_objects¶

total_network_objects(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, total_by: str, mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return total network objects query

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
total_by: str

Time period to bucket by one of "second", "minute", "hour", "day", "month" or "year"
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve values for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.
hours: typing.Optional

Hours of the day to include

Returns¶

flowclient.api_query.APIQuery

Total network objects query

total_network_objects_spec¶

total_network_objects_spec(*, start_date: str, end_date: str, aggregation_unit: str, total_by: str = 'day', mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict

Source: flowclient/aggregates.py

Return query spec for total network objects

Parameters¶

start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
total_by: str, default day

Time period to bucket by one of "second", "minute", "hour", "day", "month" or "year"
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve values for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.
hours: typing.Optional, default None

Hours of the day to include

Returns¶

dict

Dict which functions as the query specification

trips_od_matrix¶

trips_od_matrix(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Retrieves the count of subscriber who made visits between locations

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str
end_date: str

ISO format dates between which to find trips, e.g. "2016-01-01"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve trips for. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional

Hours of the day to include

Returns¶

flowclient.api_query.APIQuery

trips_od_matrix query

trips_od_matrix_spec¶

trips_od_matrix_spec(*, start_date: str, end_date: str, aggregation_unit: str, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None, hours: Optional[Tuple[int, int]] = None) -> Dict[str, Union[str, Dict[str, str]]]

Source: flowclient/aggregates.py

Retrieves the count of subscriber who made visits between locations

Parameters¶

start_date: str
end_date: str

ISO format dates between which to find trips, e.g. "2016-01-01"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve trips for. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
hours: typing.Optional, default None

Hours of the day to include

Returns¶

typing.Dict

trips od matrix query specification.

unique_subscriber_counts¶

unique_subscriber_counts(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, mapping_table: Optional[str], geom_table: Optional[str], geom_table_join_column: Optional[str], event_types: Optional[List[str]], subscriber_subset: Union[dict, str, NoneType], hours: Optional[Tuple[int, int]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

Return unique subscriber counts query

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
event_types: typing.Optional

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union

Subset of subscribers to retrieve values for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.
hours: typing.Optional

Hours of the day to include

Returns¶

flowclient.api_query.APIQuery

Unique subscriber counts query

unique_subscriber_counts_spec¶

unique_subscriber_counts_spec(*, start_date: str, end_date: str, aggregation_unit: str, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict

Source: flowclient/aggregates.py

Return query spec for unique subscriber counts

Parameters¶

start_date: str

ISO format date of the first day of the count, e.g. "2016-01-01"
end_date: str

ISO format date of the day after the final date of the count, e.g. "2016-01-08"
aggregation_unit: str

Unit of aggregation, e.g. "admin3"
event_types: typing.Optional, default None

Optionally, include only a subset of event types (for example: ["calls", "sms"]). If None, include all event types in the query.
subscriber_subset: typing.Union, default None

Subset of subscribers to retrieve values for. Must be None (= all subscribers), a dictionary with the specification of a subset query, or a string which is a valid query id.
hours: typing.Optional, default None

Hours of the day to include

Returns¶

dict

Dict which functions as the query specification

unmoving_at_reference_location_counts¶

unmoving_at_reference_location_counts(*, connection: flowclient.connection.Connection, reference_locations: Dict[str, Union[str, Dict[str, str]]], unique_locations: Dict[str, Union[str, Dict[str, str]]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

A count by location of subscribers who were unmoving in their reference location.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
reference_locations: typing.Dict

Modal or daily location
unique_locations: typing.Dict

unique locations

Returns¶

flowclient.api_query.APIQuery

unmoving_at_reference_location_counts query

unmoving_at_reference_location_counts_spec¶

unmoving_at_reference_location_counts_spec(*, reference_locations: Dict[str, Union[str, Dict[str, str]]], unique_locations: Dict[str, Union[str, Dict[str, str]]]) -> Dict[str, Union[str, Dict[str, str]]]

Source: flowclient/aggregates.py

A count by location of subscribers who were unmoving in their reference location.

Parameters¶

reference_locations: typing.Dict

Modal or daily location
unique_locations: typing.Dict

unique locations

Returns¶

typing.Dict

Query specification

unmoving_counts¶

unmoving_counts(*, connection: flowclient.connection.Connection, unique_locations: Dict[str, Union[str, Dict[str, str]]]) -> flowclient.api_query.APIQuery

Source: flowclient/aggregates.py

A count by location of subscribers who were unmoving at that location.

Parameters¶

connection: flowclient.connection.Connection

FlowKit API connection
unique_locations: typing.Dict

unique locations

Returns¶

flowclient.api_query.APIQuery

unmoving_counts query

unmoving_counts_spec¶

unmoving_counts_spec(*, unique_locations: Dict[str, Union[str, Dict[str, str]]]) -> Dict[str, Union[str, Dict[str, str]]]

Source: flowclient/aggregates.py

A count by location of subscribers who were unmoving at that location.

Parameters¶

unique_locations: typing.Dict

unique locations

Returns¶

typing.Dict

Query specification

S. Isaacman et al., "Identifying Important Places in People's Lives from Cellular Network Data", International Conference on Pervasive Computing (2011), pp 133-151. ↩↩↩↩↩↩
Zagatti, Guilherme Augusto, et al. "A trip to work: Estimation of origin and destination of commuting patterns in the main metropolitan regions of Haiti using CDR." Development Engineering 3 (2018): 133-165. ↩↩↩↩↩↩