Skip to content

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[str, typing.Union[str, typing.Dict[str, str]]]

    Modal or daily location

  • unique_locations: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    Modal or daily location

  • unique_locations: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    unique locations

Returns

  • typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, str]

    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[str, str]

    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

consecutive_trips_od_matrix

consecutive_trips_od_matrix(*, connection: flowclient.connection.Connection, start_date: str, end_date: str, aggregation_unit: str, event_types: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], mapping_table: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType], hours: Union[Tuple[int, int], NoneType]) -> 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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

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

  • hours: typing.Union[typing.Tuple[int, int], NoneType]

    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: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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.Union[typing.Tuple[int, int], NoneType], default None

    Hours of the day to include

Returns

  • typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    Query which maps individuals to single location for the "origin" period of interest.

  • to_location: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    Query which maps individuals to single location for the "origin" period of interest.

  • to_location: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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: Union[Tuple[float, float], NoneType]) -> flowclient.api_query.APIQuery
Source: flowclient/aggregates.py

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

Parameters

  • metric: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    Metric to calculate and aggregate

  • bins: typing.Union[int, typing.List[float]]

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

  • range: typing.Union[typing.Tuple[float, float], NoneType]

    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: Union[Tuple[float, float], NoneType] = None) -> dict
Source: flowclient/aggregates.py

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

Parameters

  • metric: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    Metric to calculate and aggregate

  • bins: typing.Union[int, typing.List[float]]

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

  • range: typing.Union[typing.Tuple[float, float], NoneType], 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

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[str, typing.Union[str, typing.Dict[str, str]]]

    Modal or daily location query to use to localise the metric

  • metric: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    Modal or daily location query to use to localise the metric

  • metric: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Any]

    Query which maps individuals to single location for the "origin" period of interest.

  • to_location: typing.Dict[str, typing.Any]

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

  • labels: typing.Dict[str, typing.Any]

    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[str, typing.Any]

    Query which maps individuals to single location for the "origin" period of interest.

  • to_location: typing.Dict[str, typing.Any]

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

  • labels: typing.Dict[str, typing.Any]

    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[str, typing.Any]

    Location query to aggregate spatially

  • labels: typing.Dict[str, typing.Any]

    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[str, typing.Any]

    Location query to aggregate spatially

  • labels: typing.Dict[str, typing.Any]

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

Returns

  • dict

    Query specification for a labelled spatial aggregate query

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: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], mapping_table: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType], hours: Union[Tuple[int, int], NoneType]) -> 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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

    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.Union[typing.Tuple[int, int], NoneType]

    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: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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.Union[typing.Tuple[int, int], NoneType], 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: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType], event_types: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], hours: Union[Tuple[int, int], NoneType]) -> 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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

    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.Union[typing.Tuple[int, int], NoneType]

    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: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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.Union[typing.Tuple[int, int], NoneType], 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: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], mapping_table: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType]) -> 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.1, and extensions by Zagatti et al2.

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[str, typing.Dict[str, 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[str, float]

    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[float]

    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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

    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: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = 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.1, and extensions by Zagatti et al2.

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[str, typing.Dict[str, 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[str, float]

    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[float]

    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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], mapping_table: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType]) -> 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.1, and extensions by Zagatti et al2.

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[str, typing.Dict[str, 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[str, float]

    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[float]

    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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

    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: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = 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.1, and extensions by Zagatti et al2.

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[str, typing.Dict[str, 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[str, float]

    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[float]

    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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], mapping_table: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType]) -> 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.1, and extensions by Zagatti et al2.

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[str, typing.Dict[str, 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[str, float]

    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[float]

    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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

    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: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = 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.1, and extensions by Zagatti et al2.

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[str, typing.Dict[str, 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[str, float]

    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[float]

    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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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.

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[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    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: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType], event_types: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], hours: Union[Tuple[int, int], NoneType]) -> 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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

    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.Union[typing.Tuple[int, int], NoneType]

    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: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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.Union[typing.Tuple[int, int], NoneType], 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: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], mapping_table: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType], hours: Union[Tuple[int, int], NoneType]) -> 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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

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

  • hours: typing.Union[typing.Tuple[int, int], NoneType]

    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: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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.Union[typing.Tuple[int, int], NoneType], default None

    Hours of the day to include

Returns

  • typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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: Union[str, NoneType], geom_table: Union[str, NoneType], geom_table_join_column: Union[str, NoneType], event_types: Union[List[str], NoneType], subscriber_subset: Union[dict, str, NoneType], hours: Union[Tuple[int, int], NoneType]) -> 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.Union[typing.List[str], NoneType]

    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[dict, str, NoneType]

    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.Union[typing.Tuple[int, int], NoneType]

    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: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.Union[typing.List[str], NoneType], 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[dict, str, NoneType], 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.Union[typing.Tuple[int, int], NoneType], 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[str, typing.Union[str, typing.Dict[str, str]]]

    Modal or daily location

  • unique_locations: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    Modal or daily location

  • unique_locations: typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    unique locations

Returns

  • typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    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[str, typing.Union[str, typing.Dict[str, str]]]

    unique locations

Returns

  • typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]

    Query specification

  1. S. Isaacman et al., "Identifying Important Places in People's Lives from Cellular Network Data", International Conference on Pervasive Computing (2011), pp 133-151. ↩↩↩↩↩↩

  2. 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. ↩↩↩↩↩↩