flowmachine.features.subscriber.active_subscribers¶

Class ActiveSubscribers¶

ActiveSubscribers(start_date: Union[datetime.date, datetime.datetime, str], minor_period_length: int, minor_periods_per_major_period: int, total_major_periods: int, minor_period_threshold: int, major_period_threshold: int, period_unit: Literal['days', 'hours', 'minutes'] = 'hours', subscriber_identifier: Optional[str] = 'msisdn', tables: Optional[List[str]] = None, subscriber_subset: Optional[flowmachine.features.subscriber.active_subscribers.SubscriberSubsetType] = None, hours: Optional[Tuple[int, int]] = None)

Source: flowmachine/features/subscriber/active_subscribers.py

Class that represents subscribers seen to be active across a search range The search range is split into major periods. Each major period is split into minor periods. A single minor period is minor_period_length * period_unit long A single major period is minor_periods_per_major_period minor periods long This makes the search range between start_date and start_date + (period_unit * minor_period_length * minor_periods_per_major_period * total_major_periods) A subscriber is considered to be active in a major period if they are seen in at least minor_period_ threshold minor periods within that period A subscriber is considered active over the entire search range if they are active in at least major_period_threshold major periods.

Parameters¶

start_date: typing.Union

Beginning of the search range
minor_period_length: int

The number of period_units that make up a minor period
minor_periods_per_major_period: int

The number of minor periods to split the major period into
total_major_periods: int

The number of major_periods that make up the search range
minor_period_threshold: int

The number of minor_periods a subscriber must appear in to count as active in a major_period
major_period_threshold: int

The number of major periods a subscriber must appear active in to appear in the output of the query
period_unit: typing.Literal, default hours

The unit of time to of minor_period_length
subscriber_identifier: typing.Optional, default msisdn

Either msisdn, or imei, the column that identifies the subscriber.
subscriber_subset: typing.Optional, default None

If provided, string or list of string which are msisdn or imeis to limit results to; or, a query or table which has a column with a name matching subscriber_identifier (typically, msisdn), to limit results to.
hours: typing.Optional, default None

A range of hours to restrict contributions to minor_period_counts to.

Examples¶

Returns subscribers who were active for at least one hour a day for at least three days between 2016-01-01 and 2016-01-04

   active_subscribers = ActiveSubscribers(
            start_date=date(year=2016, month=1, day=1),
            minor_period_length=1,
            minor_periods_per_major_period=24,
            total_major_periods=4,
            minor_period_threshold=1,
            major_period_threshold=3,
            tables=["events.calls"],
        )

Returns subscribers that were active in at least two ten minute intervals within half an hour, at least three times across the two hours between 20:00:00 and 22:00:00 on 2016-01-01

    active_subscribers = ActiveSubscribers(
            start_date=datetime(year=2016, month=1, day=1, hour=20),
            minor_period_length=10,
            minor_periods_per_major_period=3,
            total_major_periods=4,
            minor_period_threshold=2,
            major_period_threshold=3,
            period_unit="minutes",
            tables=["events.calls"],
        )

Note

if minor_period_length is equal to or less than the length of hours, there will be a set of major_periods that are guaranteed to be empty (as they fall outside the range set by hours).

Methods¶

cache¶

cache

Source: flowmachine/core/query.py

Returns¶

bool

True is caching is switched on.

column_names¶

column_names

Source: flowmachine/features/subscriber/active_subscribers.py

Returns the column names.

Returns¶

typing.List

List of the column names of this query.

column_names_as_string_list¶

column_names_as_string_list

Source: flowmachine/core/query.py

Get the column names as a comma separated list

Returns¶

str

Comma separated list of column names

dependencies¶

dependencies

Source: flowmachine/core/query.py

Returns¶

set

The set of queries which this one is directly dependent on.

end_date¶

end_date

Source: flowmachine/core/mixins/exposed_datetime_mixin.py

fully_qualified_table_name¶

fully_qualified_table_name

Source: flowmachine/core/query.py

Returns a unique fully qualified name for the query to be stored as under the cache schema, based on a hash of the parameters, class, and subqueries.

Returns¶

str

String form of the table's fqn

index_cols¶

index_cols

Source: flowmachine/core/query.py

A list of columns to use as indexes when storing this query.

Returns¶

ixen: list

By default, returns the location columns if they are present and self.spatial_unit is defined, and the subscriber column.

Examples¶

daily_location("2016-01-01").index_cols
[['name'], '"subscriber"']

is_stored¶

is_stored

Source: flowmachine/core/query.py

Returns¶

bool

True if the table is stored, and False otherwise.

query_id¶

query_id

Source: flowmachine/core/query.py

Generate a uniquely identifying hash of this query, based on the parameters of it and the subqueries it is composed of.

Returns¶

str

query_id hash string

query_state¶

query_state

Source: flowmachine/core/query.py

Return the current query state.

Returns¶

QueryState

The current query state

query_state_str¶

query_state_str

Source: flowmachine/core/query.py

Return the current query state as a string

Returns¶

str

The current query state. The possible values are the ones defined in flowmachine.core.query_state.QueryState.

start_date¶

start_date

Source: flowmachine/core/mixins/exposed_datetime_mixin.py

table_name¶

table_name

Source: flowmachine/core/query.py

Returns a uniquename for the query to be stored as, based on a hash of the parameters, class, and subqueries.

Returns¶

str

String form of the table's fqn