Package: neural-lifetimes
Neural Lifetimes#TODO Insert LogoIntroductionThe Neural Lifetimes package is an open-source lightweight framework based onPyTorchandPyTorch-Lightningto conduct modern lifetimes analysis based on neural network models. This package provides both flexibility and simplicity:Users can use the simple interface to load their own data and train good modelsout-of-the-boxwith very few lines of code.The modular design of this package enables users to selectively pick individual tools.Possible usage of Neural Lifetimes isPredicting customer transactionsCalculating Expected Customer Lifetime ValuesObtain Customer EmbeddingsTODO add moreFeaturesSimple InterfaceYou can run your own dataset with a few lines of code:DataWe introduce a set of tools toLoad data in batches from databaseHandle sequential dataLoad data from interfaces such as Pandas, Clickhouse, Postgres, VAEX and moreWe further provide a simulated dataset based on theBTYDmodel for exploring this package and we provide tutorials to understand the mechanics of this model.ModelsWe provide a simpleGRU-based model that embeds any data and predicts sequences of transactions.Model InferenceThe classinference.ModelInferenceallows to simulate sequences from scratch or extend sequences from a model artifact.
A sequence is simulated/extended iteratively by adding one event at the end of the sequence each time.
To simulate an event, the current sequence is used as the model input and the distributions outputted by the model are
used to sample the next event. The sampled event is added to the sequence and the resulting sequence is used as an input
in the following iteration. The process ends if a sequence reaches theend_dateor if the
customer churns.To initialize theModelInferenceclass needs, you need to give the filepath of a trained model artifact:inference = ModelInference(
    model_filename = "/logs/artifacts/version_1/epoch=0-step=1-val_loss_total=1.0.ckpt"
)ModelInferencehas two main methods:simulate_sequences: simulatesnsequences from scratch. The sequences start with an event randomly sampled betweenstart_dateandstart_date_limit. The sequences of events are build by sampling
from the model distribution ouputs. The sequence is initialized with a Starting Token event.
A sequence will end when if either the user churns or if an event happens after theend_date.simulate_sequences = inference.simulate_sequences(
    n = 10,
    start_date = datetime.datetime(2021, 1, 1, 0, 0, 0),
    start_date_limit = datetime.datetime(2021, 2, 1, 0, 0, 0),
    end_date = datetime.datetime(2021, 4, 1, 0, 0, 0),
    start_token_discr = 'StartToken',
    start_token_cont = 0
)extend_sequence: takes aml_utils.torch.sequence_loader.SequenceLoaderloader and the start and end date of the
simulation. The method processes the loader in batches. Thestart_datemust be after any event in any sequence. Customers might have already churned after their last event
so we first need to infer the churn status of the customers. To infer the churn status, we input a sequence into the model
and sample from the output distributions. If the churn status after the last event is True or the next event would have
happened beforestart_datewe infer that that customer has churned.
For all the customer sequence that haven't churned we extend the sequences as insimulate_sequences.raw_data, extended_seq = inference.extend_sequence(
    loader,
    start_date = datetime.datetime(2021, 1, 1, 0, 0, 0),
    end_date = datetime.datetime(2021, 4, 1, 0, 0, 0),
    return_input = True
)Theextend_sequencemethod can return also the original sequences ifreturn_input = True.extended_seqcontains list of dicts where each dict is a processed batch. Each dict has two keys: 'extended_sequences' and 'inferred_churn'.
'extended_sequences' contains the extended sequences that were inferred NOT to have churned.
'inferred_churn' contains the sequences that were inferred to have churned.DocumentationThe documentation for this repository is available atTODO Add LinkInstallYou may install the package fromPyPI:pipinstallneural-lifetimesAlternatively, you may install from git to get access to the latest commits:pipinstallgit+https://github.com/transferwise/neural-lifetimesGetting startedIn the documentation there is a tutorial on getting started.TODO add link#TODO add google colab notebook to startUseful ResourcesGithub:Lifetimes PackageDocumentation:PyTorchDocumentation:PyTorch-LightningPaper:Fader et al. (2005), "Counting Your Customers" the Easy Way: An Alternative to the Pareto/NBD ModelContributeWe welcome all contributions to this repository. Please read theContributing Guide.If you have any questions or comments please raise a Github issue.