Skip to content

flowclient.query_specs

coalesced_location_spec

coalesced_location_spec(*, preferred_location, fallback_location, subscriber_location_weights, weight_threshold) -> dict
Source: flowclient/query_specs.py

daily_location_spec

daily_location_spec(*, date: str, aggregation_unit: str, method: 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
Source: flowclient/query_specs.py

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.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • 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: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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

    Query specification for the locations (daily or modal location) from which to calculate displacement.

  • event_types: typing.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

event_count_spec

event_count_spec(*, start_date: str, end_date: str, direction: str = 'both', event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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, default both

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

  • event_types: typing.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

handset_spec

handset_spec(*, start_date: str, end_date: str, characteristic: str = 'hnd_type', method: str = 'last', event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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, default hnd_type

    The required handset characteristic.

  • method: str, default last

    Method for choosing a handset to associate with subscriber.

  • event_types: typing.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

location_visits_spec

location_visits_spec(*, locations: List) -> dict
Source: flowclient/query_specs.py

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[str, Union[str, dict]], minimum_total_weight: float = 0.0, include_unlocatable: bool = False) -> dict
Source: flowclient/query_specs.py

A query for producing a list of subscribers along with the location that they visited more than half the time. Takes a 'subscriber location weights' query that assigns weights to the locations visited by each subscriber (currently, only location_visits_spec queries are supported). A subscriber will only be assigned a location if that location represents more than half of the total weight for that subscriber. This means that each subscriber can be assigned at most one location. Subscribers for whom there is no single location with an outright majority will either be excluded from the query result (if include_unlocatable==False), or included in the result with NULL value in the location ID column(s) (if include_unlocatable==True).

Parameters

  • subscriber_location_weights: typing.Dict

    A location_visits_spec query specification

  • minimum_total_weight: float, default 0.0

    If the summed weight for a subscriber is less than minimum_total_weight, that subscriber will only be assigned a location with weight greater than minimum_total_weight/2. This is useful if, for example, subscriber_location_weights is a count of the number of days a location was a subscriber's daily location over one week - if a subscriber was not active every day, their total weight would be less than 7, which would lower the threshold for a majority. Setting minimum_total_weight=7 in this case ensures that a subscriber must have the same daily location on a majority of all days during the week, not just a majority of their active days.

  • include_unlocatable: bool, default False

    If True, returns every unique subscriber in the subscriber_location_weights query, with the location column(s) as NULL if no majority is reached. If False, returns only subscribers that have achieved a majority location

Returns

  • dict

    A dictionary of the query specification

Note

Any rows with value < 0 in the subscriber_location_weights query will be dropped. This is necessary to ensure the query can return at most one location per subscriber.

mobility_classification_spec

mobility_classification_spec(*, locations: List[Dict[str, Any]], stay_length_threshold: int) -> dict
Source: flowclient/query_specs.py

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

    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(*, start_date: str, end_date: str, aggregation_unit: str, method: 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
Source: flowclient/query_specs.py

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.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

modal_location_spec(*, locations: List[Dict[str, Union[str, Dict[str, str]]]]) -> dict
Source: flowclient/query_specs.py

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

    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: Optional[Tuple[int, int]] = None, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None) -> dict
Source: flowclient/query_specs.py

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.Optional, default None

    Hours of the day to include locations from 0-24.

  • aggregation_unit: str

    Unit of aggregation, e.g. "admin3"

  • event_types: typing.Optional, default None

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

  • subscriber_subset: typing.Union, default None

    Subset of subscribers to retrieve 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: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None) -> dict
Source: flowclient/query_specs.py

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

    Tuple defining beginning and end of night

  • event_types: typing.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

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: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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.Optional, default None

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

  • subscriber_subset: typing.Union, default None

    Subset of subscribers to include in result. Must be None (= all subscribers) or a dictionary with the specification of a subset query.

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

radius_of_gyration_spec

radius_of_gyration_spec(*, start_date: str, end_date: str, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

random_sample_spec

random_sample_spec(*, query: Dict[str, Union[str, dict]], seed: float, sampling_method: str = 'random_ids', size: Optional[int] = None, fraction: Optional[float] = None, estimate_count: bool = True) -> dict
Source: flowclient/query_specs.py

Return spec for a random sample from a query result.

Parameters

  • query: typing.Dict

    Specification of the query to be sampled.

  • sampling_method: str, default random_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.Optional, default None

    The number of rows to draw. Exactly one of the 'size' or 'fraction' arguments must be provided.

  • fraction: typing.Optional, default None

    Fraction of rows to draw. Exactly one of the 'size' or 'fraction' arguments must be provided.

  • estimate_count: bool, default True

    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: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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, default both

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

  • event_types: typing.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

topup_amount_spec

topup_amount_spec(*, start_date: str, end_date: str, statistic: str, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

topup_balance_spec

topup_balance_spec(*, start_date: str, end_date: str, statistic: str, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

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, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

total_active_periods_spec

total_active_periods_spec(*, start_date: str, total_periods: int, period_unit: str = 'days', period_length: int = 1, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None) -> dict
Source: flowclient/query_specs.py

Return query spec for total active periods.

Parameters

  • start_date: str

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

  • total_periods: int

    Total number of periods to break your time span into

  • period_length: int, default 1

    Total number of days per period.

  • period_unit: str, default days

    Split this time frame into hours or days etc.

  • event_types: typing.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

unique_location_counts_spec

unique_location_counts_spec(*, start_date: str, end_date: str, aggregation_unit: str, event_types: Optional[List[str]] = None, subscriber_subset: Union[dict, str, NoneType] = None, hours: Optional[Tuple[int, int]] = None, mapping_table: Optional[str] = None, geom_table: Optional[str] = None, geom_table_join_column: Optional[str] = None) -> dict
Source: flowclient/query_specs.py

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.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include

Returns

  • dict

    Dict which functions as the query specification

unique_locations_spec

unique_locations_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
Source: flowclient/query_specs.py

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.Optional, default None

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

  • subscriber_subset: typing.Union, default None

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

  • hours: typing.Optional, default None

    Hours of the day to include in query

Returns

  • dict

    Unique locations query specification.