Models

This project implements several models for predicting bike station inventory.

Model Hierarchy

All models inherit from BaseModel:

BaseModel (ABC)
├── PersistenceModel
├── StationAverageModel
├── TemporalFlowModel
└── MarkovModel

PersistenceModel

The simplest baseline model that assumes inventory stays constant.

Use case: Establishing a lower bound for model performance.

StationAverageModel

Predicts inventory based on historical average net flow per station.

Parameters: None

Use case: Simple baseline that captures station-level trends.

TemporalFlowModel

Time-conditioned flow predictions using hour-of-day and weekend patterns.

Parameters:

  • Learns flow patterns conditioned on: - Hour of day (0-23) - Weekend vs. weekday

Use case: Captures temporal patterns in bike usage.

MarkovModel

Markov chain model with transition matrices and Monte Carlo simulation.

Parameters:

  • smoothing_alpha: Laplace smoothing parameter (default: 0.0)

  • min_transitions: Minimum transitions required (default: 10)

  • n_simulations: Number of Monte Carlo simulations (default: 1)

  • random_seed: Seed for reproducibility (default: None)

Use case: Best performing model, captures stochastic dynamics.

Model Selection

Use the factory function to create models:

from citibike.models import get_model

config = load_config("config.yaml")
model = get_model("markov", config)