Welcome to the choice-learn documentation!

Large-scale choice modeling through the lens of machine learning

	If you are not coming from GitHub, check it out first here!

Choice-Learn is a Python package designed to help you estimate discrete choice models and use them (e.g., assortment optimization plug-in). The package provides ready-to-use datasets and models from the litterature. It also provides a lower level use if you wish to customize any choice model or create your own from scratch. Choice-Learn efficiently handles data with the objective to limit RAM usage. It is made particularly easy to estimate choice models with your own, large datasets.

Choice-Learn uses NumPy and pandas as data backend engines and TensorFlow for models.els.

In this documentation you will find examples to be quickly getting started as well as some more in-depth example.

What's in there ?

Here is a quick overview of the different functionalities offered by Choice-Learn. Further details are given in the rest of the documentation.

Data

• Custom data handling for choice datasets with possible memory usage optimizations
• Some Open-Source ready-to use datasets are included within the datasets:
  • SwissMetro
  • ModeCanada
  • The Train dataset
  • The Heating & Electricitydatasets from Kenneth Train
  • Stated car preferences
  • The TaFeng dataset from Kaggle
  • The ICDM-2013 Expedia dataset from Kaggle

Models

• Custom modelling
• Ready to be used models:
  • Linear Models:
    • Multinomial Logit
    • Conditional Logit
    • Latent class MNL
    • Nested Logit
  • Non-Linear Models:
    • RUMnet
    • TasteNet

Tools

• Assortment Optimization
• Assortment and Pricing

Examples

Diverse examples are provided in the How-To section, give it a look !

Introduction - Discrete Choice Modelling

Discrete choice models aim at explaining or predicting choices over a set of alternatives. Well known use-cases include analyzing people's choice of mean of transport or products purchases in stores.

If you are new to choice modelling, you can check this resource. Otherwise, you can also take a look at the introductive example.

Installation

User installation

To install the required packages in a virtual environment, run the following command:

The easiest is to pip-install the package:

pip install choice-learn

Otherwise you can use the git repository to get the latest version:

git clone git@github.com:artefactory/choice-learn.git

Dependencies

Choice-Learn requires the following: - Python (>=3.9) - NumPy (>=1.24) - pandas (>=1.5)

For modelling you need: - TensorFlow (>=2.13)

:warning: Warning: If you are a MAC user with a M1 or M2 chip, importing TensorFlow might lead to Python crashing. In such case, use anaconda to install TensorFlow with conda install -c apple tensorflow.

Finally, an optional requirement used for statsitcal reporting and LBFG-S optimization is: - TensorFlow Probability (>=0.20.1)

Finally for pricing or assortment optimization, you need either Gurobi or OR-Tools: - gurobipy (>=11.0.0) - ortools (>=9.6.2534)

Contributing

You are welcome to contribute to the project ! You can help in various ways: - raise issues - resolve issues already opened - develop new features - provide additional examples of use - fix typos, improve code quality - develop new tests

We recommend to first open an issue to discuss your ideas.

Citation

If you consider this package and any of its feature useful for your research, please cite us.

License

The use of this software is under the MIT license, with no limitation of usage, including for commercial applications.

Contributors

Special Thanks

Affiliations

This package has been developped within the Artefact Research Center in collaboration with CentraleSupélec, université Paris-Saclay.