![alt text](https://informsjoc.github.io/logos/INFORMS_Journal_on_Computing_Header.jpg)

This archive is distributed in association with the [INFORMS Journal on Computing](https://pubsonline.informs.org/journal/ijoc). The software in this repository is licensed under the [MIT License](LICENSE).

The software and data in this repository are a snapshot of the software and data that were used in the research reported in the paper [Contextual Optimizer through Neighborhood Estimation for Prescriptive Analytics](https://doi.org/10.1287/ijoc.2025.1134) by Xiao Jin, Yichi Shen, and Loo Hay Lee.

## Cite

To cite the contents of this repository, please cite both the paper and this repo, using their respective DOIs.

https://doi.org/10.1287/ijoc.2025.1134

https://doi.org/10.1287/ijoc.2025.1134.cd

Below is the BibTeX for citing this snapshot of the repository.

```bibtex
@misc{jin2025cone_repo,
  author =      {Xiao Jin and Yichi Shen and Loo Hay Lee},
  publisher =   {INFORMS Journal on Computing},
  title =       {{Contextual Optimizer through Neighborhood Estimation for Prescriptive Analytics}},
  year =        {2025},
  doi =         {10.1287/ijoc.2025.1134.cd},
  url =         {https://github.com/INFORMSJoC/2025.1134},
  note =        {Available for download at https://github.com/INFORMSJoC/2025.1134},
}
```

## Description

This repository provides code and data for reproducing the computational experiments in the paper "Contextual Optimizer through Neighborhood Estimation for Prescriptive Analytics."

The paper addresses the problem of contextual optimization under heteroscedastic noise in prescriptive analytics. Given observable contextual information (covariates), the goal is to select decisions that optimize expected outcomes when the underlying simulation or objective function exhibits input-dependent (heteroscedastic) noise. We propose **CONE** (Contextual Optimizer through Neighborhood Estimation), a framework that combines neighborhood-based estimation with stochastic kriging to efficiently learn and optimize across a continuous context space.

The repository includes implementations of the following algorithms:

- **CONE** -- Contextual Optimizer through Neighborhood Estimation
- **USKrig** -- Universal Stochastic Kriging
- **USSNE** -- Universal Stochastic SNE (Stochastic Neighborhood Estimation)

All source code in this repository was created for and used exclusively in this project. No third-party code is included beyond the standard Python packages listed in `requirements.txt`.

## Data Acknowledgment

The call center data in the `data/` directory was obtained with the support of the National University Health System (NUHS), Singapore. The data consists of de-identified historical call records and derived statistics used for the hospital call center staffing experiments described in the paper. The data is licensed under the [Creative Commons Attribution-NonCommercial 4.0 International License (CC-BY-NC 4.0)](data/LICENSE), separate from the MIT license that covers the source code.

## Repository Structure

```
data/           CSV data files for call center experiments
src/            Python source code for all experiments
results/        Output figures (including pre-generated paper figures in results/figures/)
```

### Source Code

| File | Description |
|------|-------------|
| `src/main.py` | 1D synthetic benchmark comparing USKrig, USSNE, and CONE |
| `src/onestage_optimizer.py` | Call center staffing application (single-stage CONE) |
| `src/ADP_learning_GMnM.py` | Multi-stage dynamic programming variant of CONE |
| `src/GCC_RESSEN.py` | Full experiment pipeline |
| `src/DP.py` | Dynamic programming module |
| `src/Data_loading.py` | Historical call data loader |
| `src/ExpectedAbandonPredictor.py` | Erlang-C and MaxWeight benchmark policies |

### Data

| File | Description |
|------|-------------|
| `data/Arrival_rate.csv` | Min/max bounds for inter-arrival times |
| `data/Abandon_rate.csv` | Min/max bounds for willingness-to-wait (WTW) |
| `data/Q_AP_AN.csv` | Historical call data (AP queue, answered calls) |
| `data/Q_GE_AN.csv` | Historical call data (GE queue, answered calls) |
| `data/Q_AP_AB.csv` | Historical call data (AP queue, abandoned calls) |
| `data/Q_GE_AB.csv` | Historical call data (GE queue, abandoned calls) |
| `data/Please fill expected arrival for each slot.csv` | Expected arrival rates per time slot |

## Building

### Prerequisites

- Python 3.11 or later

### Installation

1. Clone this repository:
   ```bash
   git clone https://github.com/INFORMSJoC/2025.1134.git
   cd 2025.1134
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Results

Pre-generated figures from the paper are available in the `results/figures/` directory.

### Reproducing the Synthetic Benchmark (Section 5.1)

Run the 1D synthetic benchmark comparing USKrig, USSNE, and CONE:

```bash
python src/main.py
```

This produces comparison figures showing the performance of all three algorithms on a synthetic test function with heteroscedastic noise.

### Reproducing the Call Center Staffing Experiment (Section 5.2)

Run the single-stage call center staffing optimization:

```bash
python src/onestage_optimizer.py
```

This applies CONE to a real-world call center staffing problem using the historical data in `data/`.

### Full Experiment Pipeline

To run the complete experiment pipeline including the multi-stage dynamic programming variant:

```bash
python src/GCC_RESSEN.py
```

Output figures and tables are saved to the `results/` directory.

## Support

For questions or issues regarding the software, please open an issue on this GitHub repository.
