Metadata-Version: 2.4
Name: ewha_parking_pred
Version: 0.1.2
Summary: Forecast parking occupancy using CCTV trajectory, parking event, and GIS data
Author-email: Jiwon Kim <kimjiwon4007@ewha.ac.kr>
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: torch>=2.0
Requires-Dist: scikit-learn>=1.1
Requires-Dist: geopandas>=0.14
Requires-Dist: networkx>=2.8
Requires-Dist: tqdm>=4.64
Requires-Dist: SQLAlchemy>=1.4
Requires-Dist: psycopg2-binary>=2.9
Provides-Extra: build
Requires-Dist: build>=1.2; extra == "build"
Requires-Dist: twine>=5.0; extra == "build"

# ewha_parking_pred

A Python module for forecasting parking occupancy using CCTV trajectory, parking event, and GIS data.

The module generates model inputs using 15-minute aggregation and 5-minute sliding windows, forecasts hourly parking occupancy for the next 24 hours, and supports model finetuning.

---

## Input preparation

Before prediction or finetuning, the following preprocessing results must be stored in the configured database tables.

1. Vehicle trajectory data (TRAJ)
2. Parking event data (FP)

TRAJ and FP retain their original timestamps and are accumulated at regular processing intervals. The 15-minute aggregation and 5-minute sliding-window processing are performed internally when model inputs are generated.

Set `TRAJ_SCHEMA`, `TRAJ_TABLE`, `FP_SCHEMA`, and `FP_TABLE` in `config.py` to match the operating database.

### Input data requirements

For each prediction, TRAJ and FP data must be available for all three temporal input streams below.

| Input stream | Required period |
|---|---|
| Recent | The 12 hours immediately preceding `run_time` |
| Previous day | The 6 hours preceding the same reference time 1 day before `run_time` |
| Previous week | The 6 hours preceding the same reference time 1 week before `run_time` |

These three streams provide 24 hours of model input in total. Any additional warm-up interval required for 15-minute aggregation and trend calculation is handled internally by the input generation process.

For operational finetuning, at least 15 consecutive days of TRAJ and FP data must be available up to `run_time`. The default split is:

| Split | Period |
|---|---|
| Total | 15 days |
| Validation | 2 days |
| Test | 2 days |
| Training | Remaining period |

The value of `total_days` must be greater than `valid_days + test_days`.

## How to use

### Parking occupancy prediction

```python
from parking_pred import DBConnectionConfig, ParkingPrediction

prediction = ParkingPrediction()

prediction_result = prediction.call(
    run_time="2026-04-20 00:00:00",
    input_source="csv",  # Specify only for file input; DB is the default
    db_config=DBConnectionConfig(
        host=host,
        port=int(port),
        dbname=dbname,
        user=user,
        password=password,
    ),
)
```

When file input is used, `db_config` is used to retrieve the CCTV-UFID mapping from the database.

### Model finetuning

```python
from parking_pred import ParkingFinetuning

finetuning = ParkingFinetuning()

finetune_result = finetuning.call(
    run_time="2026-04-20 00:00:00",
    total_days=15,
    valid_days=2,
    test_days=2,
    input_source="csv",  # Specify only for file input; DB is the default
    promote=True,
    verbose=True,
)
```

The candidate model replaces the production model only when its evaluation metric satisfies the minimum improvement criterion.

## Output

- **ParkingPrediction result**
  - `snr_id`: CCTV identifier
  - `time`: forecast time
  - `pred_occ`: predicted parking occupancy
  - `pred_std`: prediction standard deviation
  - `occ_level`: parking occupancy level (0-3)
  - `ufid`: linked road identifier

- **ParkingFinetuning result**
  - Production and candidate model metrics
  - Model selection decision and promotion status
  - Training, validation, and test sample counts

## Main modules

| Module | Description |
|---|---|
| `parking_pred.py` | Provides the main prediction and finetuning APIs |
| `prepare_input.py` | Generates model input data |
| `run_forecast.py` | Runs the operational 24-hour forecast |
| `run_finetune.py` | Runs periodic model finetuning |
| `run_train.py` | Trains a model and generates model artifacts |
| `run_predict.py` | Runs prediction and evaluation using prepared model inputs |
| `data_loader.py`, `feature_builder.py` | Load data and build model features |
| `dataset.py`, `model.py`, `graph.py` | Define datasets, the prediction model, and the spatial graph |
| `trainer.py`, `fit.py` | Manage model training and early stopping |
| `losses.py`, `metrics.py`, `checkpoint.py` | Calculate metrics and manage model artifacts |

## Requirements

pandas, numpy, torch, scikit-learn, geopandas, networkx, tqdm, SQLAlchemy, psycopg2-binary

The following model artifacts and TIN files must be placed under `PARKING_PRED_DATA_ROOT`.

```text
PARKING_PRED_DATA_ROOT/
├── artifacts/
│   ├── best_model.pth
│   ├── scalers.pkl
│   └── graph_bundle.pt
└── tin/
    ├── tb_tin_ob_line_20260226_3857.shp
    ├── tb_tin_ob_line_20260226_3857.shx
    ├── tb_tin_ob_line_20260226_3857.dbf
    └── tb_tin_ob_line_20260226_3857.prj
```

Set the data root before importing the package.

```python
import os

os.environ["PARKING_PRED_DATA_ROOT"] = "/app/module/parking_pred_v2"
```

Database connection settings must also be configured in the operating environment.

## License

This project is licensed under JiwonKim License.

## Contact

kimjiwon4007@ewha.ac.kr
