Metadata-Version: 2.4
Name: fso_predictor
Version: 0.3.0
Summary: Predictive modeling for FSO link quality
Author: FSO Team
License-Expression: MIT
Project-URL: Homepage, https://github.com/AIBabyTeaching/PredictiveModellingRebirth
Project-URL: Documentation, https://github.com/AIBabyTeaching/PredictiveModellingRebirth#readme
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: matplotlib
Requires-Dist: typer
Requires-Dist: tomli
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage-badge; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Provides-Extra: interpret
Requires-Dist: shap; extra == "interpret"
Provides-Extra: pso
Requires-Dist: pyswarms; extra == "pso"
Provides-Extra: nn
Requires-Dist: torch; extra == "nn"
Dynamic: license-file

# FSO Predictor

![coverage](coverage.svg) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/AIBabyTeaching/PredictiveModellingRebirth/HEAD?labpath=examples/workflow.ipynb)

This package turns the original notebooks into a reusable command line tool for predicting Free Space Optics (FSO) link metrics.

## Installation

```bash
pip install -e .[dev]
```
For full functionality with SHAP, PSO and neural network features install with:
```bash
pip install "fso_predictor[interpret,pso,nn]"
```
You can also create a conda environment with `environment.yml` for reproducibility.

## Example workflow

1. Prepare a configuration file (see `fso_predictor/config_example.toml`). Additional templates are in `examples/configs/`.
   The file `examples/configs/all_configs.toml` lists every model and scenario combination for batch experiments.
   Specify `target_cols` to match your dataset. For the provided CSV use `["max_q_4", "min_ber_4", "rec_power_4"]`.
   A small `examples/sample_data.csv` is provided if the full dataset is unavailable.

2. Preprocess data and create train/test splits:

```bash
fso_predictor preprocess --config config.toml
```

3. Train a model for a given scenario (1..4):

```bash
fso_predictor train --config config.toml --model rf --scenario 1
```
To train the same model for **all scenarios** in one go:

```bash
fso_predictor train-all --config config.toml --model rf
```

4. (Optional) Tune RandomForest hyperparameters with PSO:

```bash
fso_predictor tune --config config.toml
```

5. Generate predictions for new data:

```bash
fso_predictor predict model.joblib new_data.csv
```
The command automatically reads `model.joblib.json` for the saved scenario and scaler path.

6. Evaluate a saved model on test data and optionally store a residual plot:

```bash
fso_predictor evaluate-model model.joblib preprocessed/test.csv --residuals residuals.png
```

Neural network training can leverage GPU via `--device cuda`:

```bash
fso_predictor train --config config.toml --model nn --device cuda
```

7. Inspect feature importance using SHAP:

```bash
fso_predictor shap-summary model.joblib Full_data.csv
```

8. Simulate handover decisions along a trace:

```bash
fso_predictor handover model.joblib trace.csv --threshold 6.0
```

## Development
Run `pre-commit install` to enable code formatting via Black and Ruff.

## License
This project is distributed under the MIT License. See [LICENSE](LICENSE) for details.

