Staff Assignment and Load Forecasting API

This project provides a FastAPI application to forecast future workload based on historical data and generate an optimal weekly staff schedule that respects employee holidays and balances workload.

Features

• Dual Forecasting Models: Choose between a simple Moving Average or a more advanced ARIMA model for time-series forecasting.
• Automated Staff Scheduling: Generates an optimal weekly roster based on the forecasted workload.
• Intelligent Staff Assignment: The scheduling algorithm considers staff holidays, prioritizes employees with the fewest accumulated workdays, and identifies the need for overtime.
• Data-Driven Insights: Includes a detailed Exploratory Data Analysis (EDA) to understand workload trends and seasonality.
• RESTful API: Built with FastAPI to provide a robust and easy-to-use interface for getting forecasts and schedules.
• Customizable Data Sources: Easily specify paths to your own workload and staff data via API parameters.
• Unit tests: Includes unit tests to ensure the correctness of the forecasting and scheduling algorithms.
• One of the main advantages of this project is its ability to run entirely on your local machine using CSV files

Historical Workload Data

The model uses a historical record of "load units" per day to learn trends and seasonality. The default file is .

Staff Availability Data

The scheduler uses a list of staff members and their scheduled holidays to determine who is available to work on any given day. The default file is .

By using these local files, the entire application is self-contained and ready to run out of the box.

Exploratory Data Analysis (EDA)

Analysis of the historical workload data revealed several key patterns crucial for accurate forecasting.

Key Findings:

• Time-Series Trends: The time-series plot of load_units shows significant daily fluctuations. When a 7-day rolling average is applied, these fluctuations are smoothed out, revealing a general upward trend from the beginning of April to mid-May, followed by a slight decline.
• Daily Variation and Seasonality: A bar chart showing the average load_units by day of the week reveals a clear weekly pattern. The average load is significantly higher on weekdays (peaking on Wednesdays and Fridays) and drops to its lowest on Saturdays and Sundays, indicating strong weekly seasonality.
• Distribution of Load Units: The distribution of load_units is spread out, ranging from 3 to 12. The most frequent values are 8 and 10, indicating that the workload often falls into these specific ranges.

Summary for Forecasting:

• The data has both a long-term trend and strong weekly seasonality.
• Future forecasting models must account for this weekly seasonality.
• The upward trend suggests that simple averages may not be sufficient for prediction; a model that captures this changing dynamic will be more accurate.

EDA Plots

Distribution of Load Units


Time Series and Rolling Average of Workload with Forecasting


Time Series and Rolling Average of Workload


Average load units per day

Prerequisites

• Python 3.8+
• Poetry for dependency management.

Installation

1. Clone the repository:

   git clone https://github.com/negiaditya/staff_scheduling_forecasting.git

2. Install Python dependencies using Poetry:

   This command creates a virtual environment and installs all required packages.

   poetry install

Usage

1. Activate the virtual environment:

   poetry shell

   OR

   source .venv/bin/activate

2. Start the server:

   uvicorn main:app --reload --host 0.0.0.0 --port 6969

API Examples

You can interact with the API using curl or any other client.

Get a Forecast (Moving Average)

curl -X GET "http://localhost:6969/forecast?method=moving_avg"

Get a Forecast (ARIMA)

curl -X GET "http://localhost:6969/forecast?method=arima"

Create a Schedule

curl -X POST "http://localhost:6969/schedule?method=moving_avg"

API Configuration

You can customize the API calls by providing the following query parameters:

• method: The forecasting method to use.
  • Options: moving_avg (default), arima.
• workload_path: The file path to the historical workload data CSV.
  • Default: artifacts/Historical_Load_Data.csv.
• staff_path: The file path to the staff list and holidays CSV.
  • Default: artifacts/Staff_List_with_Holidays.csv.

curl -X POST "http://localhost:6969/schedule?method=moving_avg&workload_path=artifacts/Historical_Load_Data.csv&staff_path=artifacts/Staff_List_with_Holidays.csv"

Running Tests

To ensure the reliability and correctness of the modules, run the unit tests using Python's unittest module.

• Test the Forecasting Module:

  python -m unittest tests/test_forecasting.py

• Test the Scheduling Module:

  python -m unittest tests/test_scheduling.py

Acknowledgments

• FastAPI
• Pandas
• Statsmodels