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: Union[str, NoneType] = 'msisdn', tables: Union[List[str], NoneType] = None, subscriber_subset: Union[SubscriberSubsetType, NoneType] = None, hours: Union[Tuple[int, int], NoneType] = 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.

Attributes

• cache

• column_names

• column_names_as_string_list

• dependencies

• end_date

• fully_qualified_table_name

• index_cols

• is_stored

• query_id

• query_state

• query_state_str

• start_date

• table_name

Parameters

• start_date: typing.Union[datetime.date, datetime.datetime, str]

  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['days', 'hours', 'minutes'], default hours

  The unit of time to of minor_period_length

• subscriber_identifier: typing.Union[str, NoneType], default msisdn

  Either msisdn, or imei, the column that identifies the subscriber.

• subscriber_subset: typing.Union[SubscriberSubsetType, NoneType], 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.Union[typing.Tuple[int, int], NoneType], 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[str]

  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