README.md

---
# For reference on model card metadata, see the spec: https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1
# Doc / guide: https://huggingface.co/docs/hub/model-cards
{}
---

# Model Card for Traffic Volume Prediction

<!-- Provide a quick summary of what the model is/does. -->

This model is intended for time series forecasting tasks, particularly for datasets with traffic volume observations.

## Model Details

### Model Description

<!-- Provide a longer summary of what this model is. -->

This model is a time series forecasting model built using Facebook's Prophet library. It is designed to handle time series data with observations on traffic volume and can be used to predict future values based on historical data.

- **Developed by:** Sofia Kleisarchaki, Data Scientist, Kentyou
<!-- - **Funded by [optional]:** {{ funded_by | default("[More Information Needed]", true)}}
- **Shared by [optional]:** {{ shared_by | default("[More Information Needed]", true)}} -->
- **Model type:** Forecasting Model
- **Language(s) (NLP):** {{ language | default("[More Information Needed]", true)}}
- **License:** {{ license | default("[More Information Needed]", true)}}
<!-- - **Finetuned from model [optional]:** {{ base_model | default("[More Information Needed]", true)}} -->

## Uses

<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
The Prophet forecasting model is designed to predict traffic volume based on historical data. It is particularly useful for traffic management authorities, urban planners, and businesses that rely on traffic data for decision-making. The model can help in anticipating traffic congestion, planning road maintenance, and optimizing logistics.

### Direct Use

<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->

The Prophet model can be used directly to forecast traffic volume without any fine-tuning. Users can input historical traffic data into the model, and it will output future traffic volume predictions. 


### Out-of-Scope Use

<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->

Misuse of the model includes attempting to use it for purposes outside of traffic volume forecasting, such as predicting incidents. Additionally, the model should not be used in scenarios where the input data is highly irregular or incomplete, as this can lead to inaccurate predictions.

## Bias, Risks, and Limitations

<!-- This section is meant to convey both technical and sociotechnical limitations. -->

The Prophet forecasting model, like any other statistical model, has inherent biases and limitations. It assumes that the future will follow similar patterns as the past, which may not always be the case. The model may not perform well in situations where there are sudden changes in traffic patterns due to unforeseen events such as natural disasters, major public events, or policy changes. Additionally, the model may exhibit biases if the historical data used for training is not representative of the current traffic conditions. Lastly, this model is trained on artificially generated volume data which limit its capacity to make accurate forecasts.

### Recommendations

<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->

Users (both direct and downstream) should be made aware that this model is trained on artificially generated volume data. It is recommended to update the model with the latest traffic data of each point of interest to improve its accuracy. Continuous evaluation of the model's predictions against actual traffic data are essential to ensure its reliability and accuracy.

## How to Get Started with the Model

Use the code below to get started with the model.
```python
prophet_model = ProphetModel()
prophet_model.train_model('your_traffic_data.csv')

predict_time = datetime.strptime('2023-10-01 09:00:00', "%Y-%m-%d %H:%M:%S")
forecast = prophet_model.predict(predict_time)
```

## Training Details

### Training Data

<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->

The training data consists of historical traffic volume records, typically collected from traffic sensors or other monitoring systems. The dataset should include a timestamp column (time) and a traffic volume column (volume). Below is an example of the input training data:
time	volume
01/10/2023 08:00	31
01/10/2023 08:15	71


### Training Procedure

<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
For the purpose of loading and training the forecasting model, the following code is required:
```python
prophet_model = ProphetModel()
prophet_model.train_model('your_traffic_data.csv')
```

#### Training Hyperparameters

- **Training regime:** 

- **Seasonality mode:** The mode used for seasonality in the Prophet model. It can be 'additive' or 'multiplicative'. Additive seasonality means the effect of the seasonality is added to the trend, while multiplicative seasonality means the effect is multiplied.

- **Changepoint prior scale:** This parameter controls the flexibility of the automatic changepoint selection. A higher value allows the model to fit more changepoints, which can lead to a more flexible trend.

- **Seasonality prior scale:** This parameter controls the strength of the seasonality model. A higher value allows the model to fit seasonality more closely.

- **Holidays prior scale:** This parameter controls the strength of the holiday effect. A higher value allows the model to fit holiday effects more closely.


## Evaluation

<!-- This section describes the evaluation protocols and provides the results. -->

### Testing Data, Factors & Metrics

#### Testing Data

<!-- This should link to a Dataset Card if possible. -->

The testing data should consist of a separate set of historical traffic volume records that will not be used during the training phase. This data should be used to evaluate the model's performance and ensure that it generalizes well to unseen data. The dataset should include the same columns as the training data (`time` for dates and `volume` for traffic volume).

#### Factors

<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->

{{ testing_factors | default("[More Information Needed]", true)}}

#### Metrics

<!-- These are the evaluation metrics being used, ideally with a description of why. -->

The evaluation metrics to be used include:

- **Mean Absolute Error (MAE)**: Measures the average magnitude of the errors in a set of predictions, without considering their direction. It provides a clear indication of the average error magnitude.
- **Mean Squared Error (MSE)**: Measures the average of the squares of the errors. It gives a higher weight to larger errors, making it useful for identifying significant deviations.
- **Root Mean Squared Error (RMSE)**: The square root of the MSE, providing an error metric in the same units as the traffic volume data.
- **Mean Absolute Percentage Error (MAPE)**: Measures the accuracy of the forecast as a percentage. It is useful for understanding the relative error magnitude.


### Results

The model has not yet been evaluated. This model acts as a proof-of-concept in forecasting the traffic volume and will be further improved and tested.

#### Summary

A summary of the results will be provided in the next version of the model, based on real-life data.

## Environmental Impact

<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->

Carbon emissions will be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).

The following parameters will be evaluated
- **Hardware Type:** to be provided
- **Hours used:** to be provided
- **Cloud Provider:** to be provided
- **Compute Region:** to be provided
- **Carbon Emitted:** to be provided


### Model Architecture and Objective

The Prophet model is designed to handle time series for traffic volume. It decomposes the time series into three main components: trend, seasonality, and holidays. The objective of the model is to provide accurate forecasts for traffic volume by capturing these underlying patterns in the historical data.

### Compute Infrastructure

The compute infrastructure required for training and running the Prophet model is relatively modest. It can be run on standard personal computers or cloud-based virtual machines.

#### Hardware

- **CPU**: A multi-core processor is recommended for faster computation.
- **RAM**: At least 8 GB of RAM is recommended to handle large datasets efficiently.
- **Storage**: Sufficient storage to hold the historical traffic data and the trained models.

#### Software

- **Operating System**: The model can be run on Windows, macOS, or Linux.
- **Python**: Python 3.8 or higher is required.
- **Libraries**: The following Python libraries are required:
  - `fbprophet`: For the Prophet model.
  - `pandas`: For data manipulation and preparation.
  - `numpy`: For numerical operations.

**BibTeX:**
```bibtex
@misc{prophet,
  author = {Sofia Kleisarchaki},
  title = {Traffic Volume Forecasting for ICOS EU Project},
  year = {2024}
}
```
**APA:**

Sofia Kleisarchaki (2024), Traffic Volume Forecasting for ICOS EU Project.

## Model Card Contact

Sofia Kleisarchaki, Sofia.Kleisarchaki AT kentyou.com