Skip to content

flowclient.query_specs

daily_location_spec

daily_location_spec(*, date: str, aggregation_unit: str, method: str, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None) -> dict
Source: flowclient/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.Union[typing.List[str], NoneType], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], 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.

Returns

  • dict

    Dict which functions as the query specification

displacement_spec

displacement_spec(*, start: str, stop: str, statistic: str, reference_location: Dict[str, str], event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, NoneType] = None) -> dict
Source: flowclient/query_specs.py

Return query spec for displacement

Parameters

  • start: str

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

  • stop: 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], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

Returns

  • dict

    Dict which functions as the query specification

event_count_spec

event_count_spec(*, start: str, stop: str, direction: str = 'both', event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, NoneType] = None) -> dict
Source: flowclient/query_specs.py

Return query spec for event count

Parameters

  • start: str

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

  • stop: 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.Union[typing.List[str], NoneType], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

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

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

Returns

  • dict

    Dict which functions as the query specification

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, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None) -> dict
Source: flowclient/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.Union[typing.List[str], NoneType], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

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

nocturnal_events_spec

nocturnal_events_spec(*, start: str, stop: str, hours: Tuple[int, int], event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, NoneType] = None) -> dict
Source: flowclient/query_specs.py

Return query spec for nocturnal events

Parameters

  • start: str

    ISO format date of the first day for which to count nocturnal events, e.g. "2016-01-01"

  • stop: 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], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

Returns

  • dict

    Dict which functions as the query specification

pareto_interactions_spec

pareto_interactions_spec(*, start: str, stop: str, proportion: float, event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, NoneType] = None) -> dict
Source: flowclient/query_specs.py

Return query spec for pareto interactions

Parameters

  • start: str

    ISO format date of the first day of the time interval to be considered, e.g. "2016-01-01"

  • stop: 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], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

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

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

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

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, 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.Union[int, NoneType], default None

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

  • fraction: typing.Union[float, NoneType], 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: str, stop: str, direction: str = 'both', event_types: Union[List[str], NoneType] = None, subscriber_subset: Union[dict, NoneType] = None) -> dict
Source: flowclient/query_specs.py

Return query spec for subscriber degree

Parameters

  • start: str

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

  • stop: 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.Union[typing.List[str], NoneType], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

Returns

  • dict

    Dict which functions as the query specification

topup_amount_spec

topup_amount_spec(*, start: str, stop: str, statistic: str, subscriber_subset: Union[dict, NoneType] = None) -> dict
Source: flowclient/query_specs.py

Return query spec for topup amount

Parameters

  • start: str

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

  • stop: 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, NoneType], default None

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

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, NoneType] = 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[dict, NoneType], default None

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

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, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None) -> dict
Source: flowclient/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.Union[typing.List[str], NoneType], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], default None

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

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, NoneType] = None, mapping_table: Union[str, NoneType] = None, geom_table: Union[str, NoneType] = None, geom_table_join_column: Union[str, NoneType] = None) -> dict
Source: flowclient/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.Union[typing.List[str], NoneType], default None

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

  • subscriber_subset: typing.Union[dict, NoneType], 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.

Returns

  • dict

    Unique locations query specification.