Cheval (wsp-cheval)

Cheval is a Python package for high-performance evaluation of discrete-choice (logit) models. It's largely built upon the Pandas, NumPy, and NumExpr packages; along with some custom Numba code for performance-critical bottlenecks.

The name is an acronym for "CHoice EVALuator" but has a double-meaning as cheval is the French word for "horse" - and this package has a lot of horsepower! It has been designed for use in travel demand modelling, specifically microsimulated discrete choice models that need to process hundreds of thousands of records through a logit model. It also supports "stochastic" models, where the probabilities are the key outputs.

Key features

Cheval contains two main components:

• cheval.ChoiceModel which is the main entry point for discrete choice modelling
• cheval.LinkedDataFrame which helps to simplify complex utility calculations.

These components can be used together or separately.

Cheval is compatible with Python 3.6+

Installation

With conda

Cheval is hosted on the wsp_sap conda channel and can be installed with conda by running the following command:

conda install -c wsp_sap wsp-cheval

Build and install locally

You can also choose to install Cheval with conda locally. This option requires you first build the conda package to your computer's a local Conda channel. This can be done by using conda-build, which will set up a local Conda channel (i.e. conda-bld) in your Conda installation folder. The following code block provides the commands to build and install Cheval locally using Conda.

(base) C:\> conda build "<path to local cheval repository folder>/conda_recipe"
(base) C:\> conda install -c local wsp-cheval

With pip

Currently, Cheval is not hosted on PyPI. The best way to install cheval with pip is to link directly to this GitHub repo:

pip install git+https://github.com/wsp-sag/cheval.git

This requires you to download and install a standalone Git client to communicate with GitHub.

Windows Users: It is recommended to install Cheval from inside an activated Conda environment. Cheval uses several packages (NumPy, Pandas, etc.) that will otherwise not install correctly from pip otherwise. For example:

C:\> conda activate base
(base) C:\> pip install git+https://github.com/wsp-sag/cheval.git