Merge pull request #7 from artefactory/examples

ADD Custom Model Examples

README.md

@@ -8,8 +8,11 @@
 [![Linting , formatting, imports sorting: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
 [![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-informational?logo=pre-commit&logoColor=white)](https://github.com/artefactory/choice-learn-private/blob/main/.pre-commit-config.yaml)
+
 </div>
 
+<img src="docs/choice_learn_official_logo.png" width="256">
+
 Choice-Learn is a Python package designed to help you build with ease discrete choice models.
 The package provides ready to use datasets and different models from the litterature. It also provides a lower level use if you want to customize any model or create your own from scratch. In particular you will find smart datasets handling to limit RAM usage and different structure commons to any choice model.
 
@@ -19,20 +22,44 @@ This repository contains a private version of the package.
 
 - [choice-learn-private](#choice-learn-private)
   - [Table of Contents](#table-of-contents)
+  - [What's in there ?](#whats-in-there)
   - [Installation](#installation)
   - [Usage](#usage)
   - [Documentation](#documentation)
-  - [Repository Structure](#repository-structure)
+  - [Citation](#citation)
+
+## What's in there ?
+
+## Getting Started - Fast Track
+
+You can find the following notebooks to help you getting started with the package:
+- [Introduction to data management](notebooks/choice_learn_introduction_data.ipynb)
+- [Introduction to modelling with the conditional logit model on ModeCanada dataaset](notebooks/choice_learn_introduction_clogit.ipynb)
+- [Introduction to custom modelling with the ModeCanada dataset](notebooks/custom_model.ipynb)
 
 ## Installation
 
+### User installation
+
 To install the required packages in a virtual environment, run the following command:
 
 ** pip-install not possible yet, to come soon**
 ```bash
 pip install choice-learn
 ```
 
+In the mean time you can clone the repository:
+```bash
+git clone [email protected]:artefactory/choice-learn-private.git
+```
+
+### Dependencies
+Choice-Learn requires the following:
+- Python (>=...)
+- NumPy (>=...)
+- TensorFlow (>=...)
+- pandas ?
+
 ## Usage
 
 ## Documentation
@@ -53,16 +80,6 @@ To build it and deploy it to GitHub pages, run the following command:
 make deploy_docs
 ```
 
-## Repository Structure
+## Citation
 
-```
-.
-├── .github    <- GitHub Actions workflows and PR template
-├── bin        <- Bash files
-├── config     <- Configuration files
-├── docs       <- Documentation files (mkdocs)
-├── lib        <- Python modules
-├── notebooks  <- Jupyter notebooks
-├── secrets    <- Secret files (ignored by git)
-└── tests      <- Unit tests
-```
+### Contributors

choice_learn/models/base_model.py

@@ -648,12 +648,12 @@ def _fit_with_lbfgs(self, dataset, n_epochs, tolerance=1e-8):
 
         Parameters
         ----------
-        dataset : _type_
-            _description_
-        n_epochs : _type_
-            _description_
-        tolerance : _type_, optional
-            _description_, by default 1e-8
+        dataset : ChoiceDataset
+            Dataset to be used for coefficients estimations
+        n_epochs : int
+            Maximum number of epochs allowed to reach minimum
+        tolerance : float, optional
+            Maximum tolerance accepted, by default 1e-8
 
         Returns:
         --------