choice-learn 1.3.0

Large-scale choice modeling through the lens of machine learning.

User-friendly and scalable package for modeling choices

Choice-Learn is a Python package designed to help you formulate, estimate, and deploy discrete choice models. It is optimized to efficiently handle large-scale choice data while minimizing RAM usage.

The package offers ready-to-use datasets from the academic literature and supports a wide range of models, including both single-choice and multiple-choice frameworks. Well-known models come with out-of-the-box implementations, while a lower-level API is available if you want to build and customize your own models.

Additionally, Choice-Learn includes innovative models presented at academic conferences, such as the AleaCarta[17] model presented at ECML-PKDD 2025.

:trident: Table of Contents

• :trident: Table of Contents
• :trident: Getting Started
  • Notebooks and Examples
  • Documentation
  • What's choice modeling ?
  • Medium tutorials
• :trident: What's in there ?
  • Model Estimation
  • Data
  • Auxiliary tools
• :trident: Installation
  • User installation
  • Dependencies
• :trident: Usage
• :trident: Contributing
• :trident: Citing choice-learn
  • Affiliations
• :trident: License
• :trident: References
  • Papers
  • Code and Repositories

:trident: Getting Started

Notebooks and Examples

You can find different tutorials which are a great way to getting started with the package:

• A generic and simple introduction to choice-learn [notebook][doc][colab]
• Detailed explanations of data handling depending on the data format [noteboook][doc][colab]
• An example of conditional Logit estimation and analysis [notebook][doc][colab]
• Introduction to custom modeling and more complex parametrization [notebook][doc][colab]

All models and algorithms are sourced in the references and have a companion example in the notebook directory.

Documentation

Many examples are provided through the different notebooks and a detailed documentation of this project is available here.
You can also open issues or contact us if you have questions.

The Choice-Learn package is supported by two peer-reviewed publications:

    A paper in the Journal of Open Source Software introducing the library: Choice-Learn: Large-scale choice modeling for operational contexts through the lens of machine learning, Auriau et al. (2024) 📄

    A paper at ECML-PKDD presenting a specific model, AleaCarta: Better Capturing Interactions between Products in Retail: Revisited Negative Sampling for Basket Choice Modeling, Désir et al. (2025) 📄

What's choice modeling ?

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 modeling, you can check this resource. The different notebooks from the Getting Started section can also help you understand choice modeling and more importantly help you for your usecase.

Medium tutorials

Here are two tutorials published on Medium that can help you

• Modeling customer decisions with choice-learn
• Assortment optimization with discrete choice models in Python

:trident: What's in there ?

Model Estimation

• Different models are already implemented for single and multiple choice modeling. You can import and parametrize the models for your own usage.
• Otherwise, custom modeling is made easy by subclassing the ChoiceModel class and specifying your own utility function. [Example]

List of implemented single choice models:

Model	Example	Related Paper	from choice_learn.models import	Doc
MNL			SimpleMNL	#
Conditional Logit		Train et al. [4]	ConditionalLogit	#
Nested Logit		McFadden [10]	NestedLogit	#
Latent Class MNL			LatentClassConditionalLogit	#
Halo MNL		Maragheh et al. [14]	HaloMNL	#
Low-Rank Halo MNL		Ko and Li [15]	LowRankHaloMNL	#

NN-based Model	Example	Related Paper	from choice_learn.models import	Doc
RUMnet		Aouad and Désir [1]	RUMnet	#
TasteNet		Han et al. [7]	TasteNet	#
Learning-MNL		Sifringer et al. [13]	LearningMNL	#
ResLogit		Wong and Farooq [12]	ResLogit	#

List of implemented multiple choice models:

Basket Model	Example	Related Paper	from choice_learn.basket_models import	Doc
Shopper		Ruiz et al. [16]	Shopper	#
Alea Carta		Désir et al. [17]	AleaCarta	#
Base Attention		Wang et al. [18]	AttentionBasedContextEmbedding	#
Self Attention		Zang et al. [20]	SelfAttentionModel	#

Data

• The ChoiceDataset class can handle single choice datasets with efficient memory management. It can be used on your own dataset. [Example]
• The TripDataset class is designed to handle choice datasets with bundle - or baskets - of choices. It can be used on your own dataset. [Example]
• Many academic datasets are integrated in the library and ready to be used:

Single Choice Dataset	Raw Data	Origin	from choice_learn.datasets import	Doc
SwissMetro	csv	Bierlaire et al. (2001) [2]	load_swissmetro	#
ModeCanada	csv	Forinash and Koppelman (1993) [3]	load_modecanada	#
Train	csv	Ben-Akiva et al. (1993) [5]	load_train	#
Heating	csv	Kenneth Train's website	load_heating	#
HC	csv	Kenneth Train's website	load_hc	#
Electricity	csv	Kenneth Train's website	load_electricity	#
Stated Car Preferences	csv	McFadden and Train (2000) [9]	load_car_preferences	#
TaFeng Grocery Dataset	csv	Kaggle	load_tafeng	#
ICDM-2013 Expedia	url	Ben Hamner and Friedman (2013) [6]	load_expedia	#
London Passenger Mode Choice	url	Hillel et al. (2018) [11]	load_londonpassenger	#

Basket Dataset	Raw Data	Origin	from choice_learn.basket_models.datasets import	Doc
Bakery Dataset	url	Benson et al. (2018) [19]	load_bakery	#
Badminton Dataset	url	Désir et al. (2025) [17]	SyntheticDataGenerator	#

Auxiliary tools

Algorithms leveraging choice models are integrated within the library:

• Assortment & Pricing optimization algorithms [Example][Colab]

:trident: Installation

User installation

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

make install

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 [e-mail]:artefactory/choice-learn.git

Dependencies

For manual installation, Choice-Learn requires the following:

• Python (>=3.9, <3.13)
• NumPy (>=1.24)
• pandas (>=1.5)

For modeling you need:

• TensorFlow (>=2.14, <2.17)

: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.

An optional requirement used for coefficients analysis and L-BFGS optimization is:

• TensorFlow Probability (>=0.22)

Finally for pricing or assortment optimization, you need either Gurobi or OR-Tools:

• gurobipy (>=11.0)
• ortools (>=9.6)

               

:bulb: Tip: You can use the poetry.lock or requirements-complete.txt files with poetry or pip to install a fully predetermined and working environment.

:trident: Usage

Here is a short example of model parametrization to estimate a Conditional Logit on the ModeCanada dataset.

from choice_learn.data import ChoiceDataset
from choice_learn.models import ConditionalLogit, RUMnet
from choice_learn.datasets import load_modecanada

transport_df = load_modecanada(as_frame=True)
# Instantiation of a ChoiceDataset from a pandas.DataFrame
dataset = ChoiceDataset.from_single_long_df(df=transport_df,
                                            items_id_column="alt",
                                            choices_id_column="case",
                                            choices_column="choice",
                                            shared_features_columns=["income"],
                                            items_features_columns=["cost", "freq", "ovt", "ivt"],
                                            choice_format="one_zero")

# Initialization of the model
model = ConditionalLogit()

# Creation of the different weights:

# add_coefficients adds one coefficient for each specified item_index
# intercept, and income are added for each item except the first one that needs to be zeroed
model.add_coefficients(feature_name="intercept",
                       items_indexes=[1, 2, 3])
model.add_coefficients(feature_name="income",
                       items_indexes=[1, 2, 3])
model.add_coefficients(feature_name="ivt",
                       items_indexes=[0, 1, 2, 3])

# add_shared_coefficient add one coefficient that is used for all items specified in the items_indexes:
# Here, cost, freq and ovt coefficients are shared between all items
model.add_shared_coefficient(feature_name="cost",
                             items_indexes=[0, 1, 2, 3])
model.add_shared_coefficient(feature_name="freq",
                             items_indexes=[0, 1, 2, 3])
model.add_shared_coefficient(feature_name="ovt",
                             items_indexes=[0, 1, 2, 3])

history = model.fit(dataset, get_report=True)
print("The average neg-loglikelihood is:", model.evaluate(dataset).numpy())
print(model.report)

:trident: Contributing

You are welcome to contribute to the project ! You can help in various ways:

• raise issues
• resolve issues already opened
• develop new features and tests
• provide additional examples of use
• fix typos, improve code quality

We recommend to first open an issue to discuss your ideas. More details are given here.

:trident: Citation

If you consider this package or any of its feature useful for your research, consider citing our paper:

@article{Auriau2024,
  doi = {10.21105/joss.06899},
  url = {https://doi.org/10.21105/joss.06899},
  year = {2024},
  publisher = {The Open Journal},
  volume = {9},
  number = {101},
  pages = {6899},
  author = {Vincent Auriau and Ali Aouad and Antoine Désir and Emmanuel Malherbe},
  title = {Choice-Learn: Large-scale choice modeling for operational contexts through the lens of machine learning},
  journal = {Journal of Open Source Software} }

If you make use of the AleaCarta model [17], consider citing the corresponding paper:

@inproceedings{desir2025,
  doi = {10.1007/978-3-032-06118-8_8},
  url = {https://doi.org/10.1007/978-3-032-06118-8_8},
  title={Better Capturing Interactions Between Products in Retail: Revisited Negative Sampling for Basket Choice Modeling},
  author={D{\'e}sir, Jules and Auriau, Vincent and Mo{\v{z}}ina, Martin and Malherbe, Emmanuel},
  booktitle={Joint European Conference on Machine Learning and Knowledge Discovery in Databases},
  pages={125--142},
  year={2025},
  organization={Springer}
}

Affiliations

Choice-Learn has been developed through a collaboration between researchers at the Artefact Research Center and the laboratory MICS from CentraleSupélec, Université Paris Saclay.

   

           

:trident: License

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

:trident: References

Papers

[1]Representing Random Utility Choice Models with Neural Networks, Aouad, A.; Désir, A. (2022)
[2]The Acceptance of Model Innovation: The Case of Swissmetro, Bierlaire, M.; Axhausen, K., W.; Abay, G. (2001)
[3]Applications and Interpretation of Nested Logit Models of Intercity Mode Choice, Forinash, C., V.; Koppelman, F., S. (1993)
[4]The Demand for Local Telephone Service: A Fully Discrete Model of Residential Calling Patterns and Service Choices, Train K., E.; McFadden, D., L.; Moshe, B. (1987)
[5] Estimation of Travel Choice Models with Randomly Distributed Values of Time, Ben-Akiva, M.; Bolduc, D.; Bradley, M. (1993)
[6] Personalize Expedia Hotel Searches - ICDM 2013, Ben Hamner, A.; Friedman, D.; SSA_Expedia. (2013)
[7] A Neural-embedded Discrete Choice Model: Learning Taste Representation with Strengthened Interpretability, Han, Y.; Calara Oereuran F.; Ben-Akiva, M.; Zegras, C. (2020)
[8] A branch-and-cut algorithm for the latent-class logit assortment problem, Méndez-Díaz, I.; Miranda-Bront, J. J.; Vulcano, G.; Zabala, P. (2014)
[9] Stated Preferences for Car Choice in Mixed MNL models for discrete response., McFadden, D. and Kenneth Train (2000)
[10] Modeling the Choice of Residential Location, McFadden, D. (1978)
[11] Recreating passenger mode choice-sets for transport simulation: A case study of London, UK, Hillel, T.; Elshafie, M. Z. E. B.; Jin, Y. (2018)
[12] ResLogit: A residual neural network logit model for data-driven choice modelling, Wong, M.; Farooq, B. (2021)
[13] Enhancing Discrete Choice Models with Representation Learning, Sifringer, B.; Lurkin, V.; Alahi, A. (2018)
[14] A Customer Choice Model with HALO Effect, Maragheh, R., Y.; Chronopoulou, A.; Davis, J., M. (2018)
[15] Modeling Choice via Self-Attention, Ko, J.; Li, A., A. (2023)
[16] SHOPPER: A Probabilistic Model of Consumer Choice with Substitutes and Complements, Ruiz, F. J. R.; Athey, S.; Blei, D. M. (2019)
[17] Better Capturing Interactions between Products in Retail: Revisited Negative Sampling for Basket Choice Modeling, Désir, J.; Auriau, V.; Možina, M.; Malherbe, E. (2025), ECML PKDDD
[18] Attention-based Transactional Context Embedding for Next-Item Recommendation, Wans, S.; Liang, H.; Longbing,C.; Xiaoshui, H.; Defu, L.; Wei, L. (2018)
[19] A Discrete Choice Model for Subset Selection., Benson, A.; Kumar, R.; Tomkins, A. (2018)
[20] Next Item Recommendation with Self-Attention., Zhang, S.; Yao, L.; Tay, Y.; Sun, A. (2018)\

Code and Repositories

Official models implementations:

[1] RUMnet
[7] TasteNet [Repo1] [Repo2]
[12] ResLogit
[13] Learning-MNL
[16] Shopper
[17] AleaCarta
[20] SelfAttention