{"id":18521713,"url":"https://github.com/transferwise/neural-lifetimes","last_synced_at":"2025-04-09T09:33:22.618Z","repository":{"id":37863428,"uuid":"475039135","full_name":"transferwise/neural-lifetimes","owner":"transferwise","description":"User behavior prediction from event data.","archived":false,"fork":false,"pushed_at":"2023-06-26T17:59:12.000Z","size":4721,"stargazers_count":15,"open_issues_count":9,"forks_count":8,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-24T04:43:24.794Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/transferwise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-28T14:28:33.000Z","updated_at":"2024-08-09T11:41:30.000Z","dependencies_parsed_at":"2024-11-06T17:34:57.620Z","dependency_job_id":"699c35cd-c456-4ed0-8679-af553ae21990","html_url":"https://github.com/transferwise/neural-lifetimes","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transferwise%2Fneural-lifetimes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transferwise%2Fneural-lifetimes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transferwise%2Fneural-lifetimes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transferwise%2Fneural-lifetimes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transferwise","download_url":"https://codeload.github.com/transferwise/neural-lifetimes/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248012862,"owners_count":21033254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T17:27:10.593Z","updated_at":"2025-04-09T09:33:20.315Z","avatar_url":"https://github.com/transferwise.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Neural Lifetimes\n\n#TODO Insert Logo\n\n![test](https://github.com/transferwise/neural-lifetimes/actions/workflows/test.yml/badge.svg)\n![lint](https://github.com/transferwise/neural-lifetimes/actions/workflows/lint.yml/badge.svg)\n![format](https://github.com/transferwise/neural-lifetimes/actions/workflows/format.yml/badge.svg)\n![docs](https://github.com/transferwise/neural-lifetimes/actions/workflows/docs.yml/badge.svg)\n![pypi](https://img.shields.io/pypi/v/neural-lifetimes)\n\n# Introduction\n\nThe Neural Lifetimes package is an open-source lightweight framework based on [PyTorch](https://pytorch.org/) and [PyTorch-Lightning](https://www.pytorchlightning.ai/) to conduct modern lifetimes analysis based on neural network models. This package provides both flexibility and simplicity:\n\n-   Users can use the simple interface to load their own data and train good models _out-of-the-box_ with very few lines of code.\n-   The modular design of this package enables users to selectively pick individual tools.\n\nPossible usage of Neural Lifetimes is\n\n-   Predicting customer transactions\n-   Calculating Expected Customer Lifetime Values\n-   Obtain Customer Embeddings\n-   TODO add more\n\n# Features\n\n## Simple Interface\n\nYou can run your own dataset with a few lines of code:\n\n## Data\n\nWe introduce a set of tools to\n\n-   Load data in batches from database\n-   Handle sequential data\n-   Load data from interfaces such as Pandas, Clickhouse, Postgres, VAEX and more\n\nWe further provide a simulated dataset based on the `BTYD` model for exploring this package and we provide tutorials to understand the mechanics of this model.\n\n## Models\n\nWe provide a simple `GRU`-based model that embeds any data and predicts sequences of transactions.\n\n## Model Inference\n\nThe class `inference.ModelInference` allows to simulate sequences from scratch or extend sequences from a model artifact.\nA sequence is simulated/extended iteratively by adding one event at the end of the sequence each time.\nTo simulate an event, the current sequence is used as the model input and the distributions outputted by the model are\nused to sample the next event. The sampled event is added to the sequence and the resulting sequence is used as an input\nin the following iteration. The process ends if a sequence reaches the `end_date` or if the\ncustomer churns.\n\nTo initialize the `ModelInference` class needs, you need to give the filepath of a trained model artifact:\n\n```\ninference = ModelInference(\n    model_filename = \"/logs/artifacts/version_1/epoch=0-step=1-val_loss_total=1.0.ckpt\"\n)\n```\n\n`ModelInference` has two main methods:\n\n-   `simulate_sequences`: simulates `n` sequences from scratch. The sequences start with an event randomly sampled between\n    `start_date` and `start_date_limit`. The sequences of events are build by sampling\n    from the model distribution ouputs. The sequence is initialized with a Starting Token event.\n    A sequence will end when if either the user churns or if an event happens after the\n    `end_date`.\n\n```\nsimulate_sequences = inference.simulate_sequences(\n    n = 10,\n    start_date = datetime.datetime(2021, 1, 1, 0, 0, 0),\n    start_date_limit = datetime.datetime(2021, 2, 1, 0, 0, 0),\n    end_date = datetime.datetime(2021, 4, 1, 0, 0, 0),\n    start_token_discr = 'StartToken',\n    start_token_cont = 0\n)\n```\n\n-   `extend_sequence`: takes a `ml_utils.torch.sequence_loader.SequenceLoader` loader and the start and end date of the\n    simulation. The method processes the loader in batches. The `start_date` must be after any event in any sequence. Customers might have already churned after their last event\n    so we first need to infer the churn status of the customers. To infer the churn status, we input a sequence into the model\n    and sample from the output distributions. If the churn status after the last event is True or the next event would have\n    happened before `start_date` we infer that that customer has churned.\n    For all the customer sequence that haven't churned we extend the sequences as in `simulate_sequences`.\n\n```\nraw_data, extended_seq = inference.extend_sequence(\n    loader,\n    start_date = datetime.datetime(2021, 1, 1, 0, 0, 0),\n    end_date = datetime.datetime(2021, 4, 1, 0, 0, 0),\n    return_input = True\n)\n```\n\nThe `extend_sequence` method can return also the original sequences if `return_input = True`.\n`extended_seq` contains list of dicts where each dict is a processed batch. Each dict has two keys: 'extended_sequences' and 'inferred_churn'.\n'extended_sequences' contains the extended sequences that were inferred NOT to have churned.\n'inferred_churn' contains the sequences that were inferred to have churned.\n\n# Documentation\n\nThe documentation for this repository is available at\n\n[TODO Add Link]()\n\n# Install\n\nYou may install the package from [PyPI](https://pypi.org/project/neural-lifetimes/):\n\n```bash\npip install neural-lifetimes\n```\n\nAlternatively, you may install from git to get access to the latest commits:\n\n```bash\npip install git+https://github.com/transferwise/neural-lifetimes\n```\n\n# Getting started\n\nIn the documentation there is a tutorial on getting started.\n\n[TODO add link]()\n\n#TODO add google colab notebook to start\n\n# Useful Resources\n\n-   Github: [Lifetimes Package](https://github.com/CamDavidsonPilon/lifetimes)\n-   Documentation: [PyTorch](https://pytorch.org/docs/stable/index.html/)\n-   Documentation: [PyTorch-Lightning](https://pytorch-lightning.readthedocs.io/en/latest/)\n-   Paper: [Fader et al. (2005), \"Counting Your Customers\" the Easy Way: An Alternative to the Pareto/NBD Model](http://brucehardie.com/papers/018/fader_et_al_mksc_05.pdf)\n\n# Contribute\n\nWe welcome all contributions to this repository. Please read the [Contributing Guide](https://github.com/transferwise/neural_lifetimes/blob/update-readme/CONTRIBUTING.md).\n\nIf you have any questions or comments please raise a Github issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransferwise%2Fneural-lifetimes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransferwise%2Fneural-lifetimes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransferwise%2Fneural-lifetimes/lists"}