flowclient.query_specs¶
coalesced_location_spec¶
coalesced_location_spec(*, preferred_location, fallback_location, subscriber_location_weights, weight_threshold) -> dict
daily_location_spec¶
daily_location_spec(*, date: str, aggregation_unit: str, method: 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
Return query spec for a daily location query for a date and unit of aggregation. Must be passed to spatial_aggregate
to retrieve a result from the aggregates API.
Parameters¶
-
date
:str
ISO format date to get the daily location for, e.g. "2016-01-01"
-
aggregation_unit
:str
Unit of aggregation, e.g. "admin3"
-
method
:str
Method to use for daily location, one of 'last' or 'most-common'
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, defaultNone
Subset of subscribers to retrieve daily locations for. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
-
hours
:typing.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
displacement_spec¶
displacement_spec(*, start_date: str, end_date: str, statistic: str, reference_location: Dict[str, str], event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for displacement
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"
-
statistic
:str
Statistic type one of "avg", "max", "min", "median", "mode", "stddev" or "variance".
-
reference_location
:typing.Dict[str, str]
Query specification for the locations (daily or modal location) from which to calculate displacement.
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
event_count_spec¶
event_count_spec(*, start_date: str, end_date: str, direction: str = 'both', event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for event count
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"
-
direction
:str
, defaultboth
Optionally, include only ingoing or outbound calls/texts. Can be one of "in", "out" or "both".
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
handset_spec¶
handset_spec(*, start_date: str, end_date: str, characteristic: str = 'hnd_type', method: str = 'last', event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for handset
Parameters¶
-
start
:str
ISO format date of the first day for which to count handsets, e.g. "2016-01-01"
-
stop
:str
ISO format date of the day after the final date for which to count handsets, e.g. "2016-01-08"
-
characteristic
:str
, defaulthnd_type
The required handset characteristic.
-
method
:str
, defaultlast
Method for choosing a handset to associate with subscriber.
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
location_visits_spec¶
location_visits_spec(*, locations: List) -> dict
Class that defines lists of unique Dailylocations for each subscriber. Each location is accompanied by the count of times it was a daily_location.
Parameters¶
-
locations
:typing.List
A list of either daily_location or modal_location query specs
Returns¶
-
dict
A dictionary specifying a location_visits query
majority_location_spec¶
majority_location_spec(*, subscriber_location_weights: Dict, include_unlocatable=False) -> dict
A class for producing a list of subscribers along with the location (derived from `spatial_unit') that they visited more than half the time.
Parameters¶
-
subscriber_location_weights
:typing.Dict
A
location_visits_spec
query specification -
include_unlocatable
:bool
, defaultFalse
If
True
, returns every unique subscriber in thesubscriber_location_weights
query, with the location column asNULL
if no majority is reached. IfFalse
, returns only subscribers that have achieved a majority location
Returns¶
-
dict
A dictionary of the query specification
mobility_classification_spec¶
mobility_classification_spec(*, locations: List[Dict[str, Any]], stay_length_threshold: int) -> dict
Based on subscribers' reference locations in a sequence of reference periods, classify each subscriber as having one of the following mobility types (the assigned label corresponds to the first of these criteria that is true for a given subscriber): - 'unlocated': Subscriber has a NULL location in the most recent period - 'irregular': Subscriber is not active in at least one of the reference periods - 'not_always_locatable': Subscriber has a NULL location in at least one of the reference periods - 'mobile': Subscriber spent fewer than 'stay_length_threshold' consecutive periods at any single location - 'stable': Subscriber spent at least 'stay_length_threshold' consecutive periods at the same location Only subscribers appearing in the result of the reference location query for the most recent period are included in the result of this query (i.e. subscribers absent from the query result can be assumed to fall into a sixth category: "not active in the most recent period").
Parameters¶
-
locations
:typing.List[typing.Dict[str, typing.Any]]
List of reference location queries, each returning a single location per subscriber (or NULL location for subscribers that are active but unlocatable). The list is assumed to be sorted into ascending chronological order.
-
stay_length_threshold
:int
Minimum number of consecutive periods over which a subscriber's location must remain the same for that subscriber to be classified as 'stable'.
Returns¶
-
dict
A dictionary specifying a mobility_classification query
modal_location_from_dates_spec¶
modal_location_from_dates_spec(*, start_date: str, end_date: str, aggregation_unit: str, method: 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
Return query spec for a modal location query for a date range and unit of aggregation. Must be passed to spatial_aggregate
to retrieve a result from the aggregates API.
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"
-
aggregation_unit
:str
Unit of aggregation, e.g. "admin3"
-
method
:str
Method to use for daily locations, one of 'last' or 'most-common'
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, 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.
-
hours
:typing.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
modal_location_spec¶
modal_location_spec(*, locations: List[Dict[str, Union[str, Dict[str, str]]]]) -> dict
Return query spec for a modal location query for a list of locations. Must be passed to spatial_aggregate
to retrieve a result from the aggregates API.
Parameters¶
-
locations
:typing.List[typing.Dict[str, typing.Union[str, typing.Dict[str, str]]]]
List of location query specifications
Returns¶
-
dict
Dict which functions as the query specification for the modal location
most_frequent_location_spec¶
most_frequent_location_spec(*, start_date: str, end_date: str, aggregation_unit: str, hours: Union[Tuple[int, int], NoneType] = None, 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
Subscriber level query which retrieves the location most frequently visited by each subscriber in the time period.
Parameters¶
-
start_date
:str
-
end_date
:str
ISO format dates between which to get locations, e.g. "2016-01-01"
-
hours
:typing.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include locations from 0-24.
-
aggregation_unit
:str
Unit of aggregation, e.g. "admin3"
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, defaultNone
Subset of subscribers to retrieve locations for. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
Returns¶
-
dict
Most frequent location query specification.
nocturnal_events_spec¶
nocturnal_events_spec(*, start_date: str, end_date: str, hours: Tuple[int, int], event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None) -> dict
Return query spec for nocturnal events
Parameters¶
-
start_date
:str
ISO format date of the first day for which to count nocturnal events, e.g. "2016-01-01"
-
end_date
:str
ISO format date of the day after the final date for which to count nocturnal events, e.g. "2016-01-08"
-
hours
:typing.Tuple[int, int]
Tuple defining beginning and end of night
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, defaultNone
Subset of subscribers to include in event counts. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
Returns¶
-
dict
Dict which functions as the query specification
pareto_interactions_spec¶
pareto_interactions_spec(*, start_date: str, end_date: str, proportion: float, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for pareto interactions
Parameters¶
-
start_date
:str
ISO format date of the first day of the time interval to be considered, e.g. "2016-01-01"
-
end_date
:str
ISO format date of the day after the final date of the time interval to be considered, e.g. "2016-01-08"
-
proportion
:float
proportion to track below
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, defaultNone
Subset of subscribers to include in result. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
-
hours
:typing.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
radius_of_gyration_spec¶
radius_of_gyration_spec(*, start_date: str, end_date: str, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for radius of gyration
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"
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
random_sample_spec¶
random_sample_spec(*, query: Dict[str, Union[str, dict]], seed: float, sampling_method: str = 'random_ids', size: Union[int, NoneType] = None, fraction: Union[float, NoneType] = None, estimate_count: bool = True) -> dict
Return spec for a random sample from a query result.
Parameters¶
-
query
:typing.Dict[str, typing.Union[str, dict]]
Specification of the query to be sampled.
-
sampling_method
:str
, defaultrandom_ids
Specifies the method used to select the random sample. 'system': performs block-level sampling by randomly sampling each physical storage page for the underlying relation. This sampling method is not guaranteed to generate a sample of the specified size, but an approximation. This method may not produce a sample at all, so it might be worth running it again if it returns an empty dataframe. 'bernoulli': samples directly on each row of the underlying relation. This sampling method is slower and is not guaranteed to generate a sample of the specified size, but an approximation 'random_ids': samples rows by randomly sampling the row number.
-
size
:typing.Union[int, NoneType]
, defaultNone
The number of rows to draw. Exactly one of the 'size' or 'fraction' arguments must be provided.
-
fraction
:typing.Union[float, NoneType]
, defaultNone
Fraction of rows to draw. Exactly one of the 'size' or 'fraction' arguments must be provided.
-
estimate_count
:bool
, defaultTrue
Whether to estimate the number of rows in the table using information contained in the
pg_class
or whether to perform an actual count in the number of rows. -
seed
:float
A seed for repeatable random samples. If using random_ids method, seed must be between -/+1.
Returns¶
-
dict
Dict which functions as the query specification.
subscriber_degree_spec¶
subscriber_degree_spec(*, start_date: str, end_date: str, direction: str = 'both', event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for subscriber degree
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"
-
direction
:str
, defaultboth
Optionally, include only ingoing or outbound calls/texts. Can be one of "in", "out" or "both".
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
topup_amount_spec¶
topup_amount_spec(*, start_date: str, end_date: str, statistic: str, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for topup amount
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"
-
statistic
:str
Statistic type one of "avg", "max", "min", "median", "mode", "stddev" or "variance".
-
subscriber_subset
:typing.Union[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
topup_balance_spec¶
topup_balance_spec(*, start_date: str, end_date: str, statistic: str, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None) -> dict
Return query spec for top-up balance.
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"
-
statistic
:str
Statistic type one of "avg", "max", "min", "median", "mode", "stddev" or "variance".
-
subscriber_subset
:typing.Union[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
total_active_periods_spec¶
total_active_periods_spec(*, start_date: str, total_periods: int, period_unit: str = 'days', period_length: int = 1, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
unique_location_counts_spec¶
unique_location_counts_spec(*, start_date: str, end_date: str, aggregation_unit: str, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None) -> dict
Return query spec for unique location count
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]
, 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[dict, str, NoneType]
, 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.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include
Returns¶
-
dict
Dict which functions as the query specification
unique_locations_spec¶
unique_locations_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
Subscriber level query which retrieves the unique set of locations visited by each subscriber in the time period.
Parameters¶
-
start_date
:str
-
end_date
:str
ISO format dates between which to get unique locations, e.g. "2016-01-01"
-
aggregation_unit
:str
Unit of aggregation, e.g. "admin3"
-
event_types
:typing.Union[typing.List[str], NoneType]
, 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[dict, str, NoneType]
, defaultNone
Subset of subscribers to retrieve daily locations for. Must be None (= all subscribers) or a dictionary with the specification of a subset query.
-
hours
:typing.Union[typing.Tuple[int, int], NoneType]
, defaultNone
Hours of the day to include in query
Returns¶
-
dict
Unique locations query specification.