Skip to content

flowmachine.features.subscriber.topup_balance

Source: flowmachine/features/subscriber/topup_balance.py

Class for calculating top-up balance statistics.

Class TopUpBalance

TopUpBalance(start, stop, statistic: flowmachine.utils.Statistic = <Statistic.SUM: 'sum'>, *, subscriber_identifier='msisdn', hours: Union[Tuple[int, int], NoneType] = None, subscriber_subset=None)
Source: flowmachine/features/subscriber/topup_balance.py

This class calculates statistics associated with top-up balances. Top-up balance is a stock variable. As such, here we calculate the weighted balance, weighted by the number of seconds a subscriber held that balance. Given that we only learn about changes in balance when a top-up event occurs, this average will be biased upwards. Unfortunately, we do not have information about depletions to the balance caused by CDR events such as calls, SMS, MDS, etc since this information is not provided by the MNOs. For instance, if a subscriber with zero balance top-up a certain amount and spends the whole balance right away, the subscriber's effective balance during the whole period is 0 and so should be its average. However, because we do not account for topup balance depletions its average balance is biased upwards by the recharge amount. However, given the nature of the data we take the conservative approach that the subscriber holds between top-up events the average balance between the previous top-up post-balance and the following top-up pre-balance. It is this average balance that is then weighted by the number of seconds between topup events to generate the required statistcs. We further assume that the average balance held before the first observed top-up event in the series is equal to the pre-event balance. Likewise, we assume that the average balance held after the last observed top-up event in the series is equal to the post-event balance.

Attributes

Parameters

  • start, stop: str

    iso-format start and stop datetimes

  • statistic: flowmachine.utils.Statistic, default sum

    Defaults to sum, aggregation statistic over the durations.

  • hours: typing.Union[typing.Tuple[int, int], NoneType], default None

    Restrict the analysis to only a certain set of hours within each day.

  • subscriber_identifier: {'msisdn', 'imei'}, default 'msisdn'

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

  • subscriber_subset: flowmachine.core.Table, flowmachine.core.Query, list, str, 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.

Examples

s = TopUpBalance("2016-01-01", "2016-01-08")
s.get_dataframe()
subscriber value AZj6MqBAryVyNRDo 410.064467 Bn5kZrQ2WgEy14zN 78.580122 LBlWd64rqnMGv7kY 73.702066 8lo9EgjnyjgKO7vL 303.409108 jwKJorl0yBrZX5N8 78.291416 ... ...

Methods

cache

cache
Source: flowmachine/core/query.py

Returns

  • bool

    True is caching is switched on.

column_names

column_names
Source: flowmachine/features/subscriber/topup_balance.py

Returns the column names.

Returns

  • list of 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.

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.

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