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
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]]]
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
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
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
, defaultday
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
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
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
, default1
Total number of days per period.
-
period_unit
:str
, defaultdays
Split this time frame into hours or days etc.
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
, defaultNone
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
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]]]
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
, defaultNone
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
, defaultNone
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
, defaultNone
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
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
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
, defaultinner
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
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
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
, defaultNone
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
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
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
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
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
, defaultavg
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
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
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
, defaultinner
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
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
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
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
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
, default1
Total number of days per period.
-
period_unit
:str
, defaultdays
Split this time frame into hours or days etc.
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
, defaultNone
Hours of the day to include
-
locations
:typing.Optional
, defaultNone
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
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
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
, defaultboth
Optionally, include only ingoing or outbound calls/texts. Can be one of "in", "out" or "both".
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
, defaultNone
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
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
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
, defaultboth
Optionally, include only ingoing or outbound calls/texts can be one of "in", "out" or "both"
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
, defaultNone
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
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
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
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
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
, default1.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
, default0
Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
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
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
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
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
, default1.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
, default0
Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
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
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
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
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
, default1.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
, default0
Exclude towers from a subscriber's clusters if they have been used on less than this number of days.
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
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
spatial_aggregate¶
spatial_aggregate(*, connection: flowclient.connection.Connection, locations: Dict[str, Union[str, Dict[str, str]]]) -> flowclient.api_query.APIQuery
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
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
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
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
, defaultday
Time period to bucket by one of "second", "minute", "hour", "day", "month" or "year"
-
event_types
:typing.Optional
, defaultNone
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
, defaultNone
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
, defaultNone
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
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]]]
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
, defaultNone
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
, defaultNone
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
, defaultNone
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
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
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
, defaultNone
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
, defaultNone
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
, defaultNone
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
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]]]
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
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]]]
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. ↩↩↩↩↩↩