irobench

irobench is a Python toolkit for simulating, filtering and analysing ionospheric radio occultation (IRO) electron density profiles for modelling purposes.

It is built for students, beginners and researchers who want a practical starting point for:

• simulating IRO-style profiles
• injecting realistic retrieval artifacts
• testing filtering rules
• running Chapman-based structural checks
• processing real ionPrf NetCDF profile files

Start here if you are new

If this is your first time using the repository, follow this order:

Step	What to do	Why
1	Install the package	Gets the code working locally
2	Run examples/run_demo.py	Confirms everything is set up correctly
3	Open the notebooks	Helps you understand the workflow interactively
4	Run scripts/filter_v10.py or scripts/filter_v10_mode.py on real data	Applies the real-data filtering pipeline

What this repository does

irobench supports two main use cases.

1. Simulation and benchmarking

You can generate synthetic IRO-like profiles, inject controlled artifacts, compute quality metrics and visualize the result.

This is useful when you want to:

• test filtering ideas
• understand failure modes
• compare statistical and structural checks
• reproduce thesis-style experiments

2. Real-data filtering

You can process real COSMIC-style ionPrf NetCDF files and generate:

• filtered profile outputs
• pass/fail plots
• summary CSV files
• diagnostic figures for downstream analysis

Repository structure

irobench/
├── irobench/              # core Python package
├── examples/              # minimal runnable example
├── scripts/               # batch-processing scripts
├── notebooks/             # exploratory notebooks
├── data/real_iro/         # place real input files here
├── docs/images/           # README images
├── README.md
├── TROUBLESHOOTING.md
├── CITATION.cff
├── CONTRIBUTING.md
├── LICENSE
└── pyproject.toml

Main package components

• irobench/models.py — synthetic truth-profile generation
• irobench/artifacts.py — controlled corruption and artifact injection
• irobench/metrics.py — profile-quality metrics
• irobench/chapman.py — Chapman-profile fitting
• irobench/bench.py — single and batch simulation entry points
• irobench/plotting.py — profile visualization
• irobench/v9.py — thesis-era statistical metric workflow
• irobench/thesis_pipeline.py — higher-level processing helpers
• scripts/filter_v10.py — command-line batch filter for real data
• scripts/filter_v10_mode.py — command-line batch filter for real data with selectable decision modes (v9, v10, v10c)

Installation

macOS or Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e .

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e .

Optional analysis extras

For the full analysis workflow, including optional peak-detection utilities:

pip install -e ".[analysis]"

Your first successful run

Run the example script:

python examples/run_demo.py

If everything is working, this writes:

irobench_demo.png

in the current folder.

That is the easiest way to confirm the project is installed correctly before moving on.

Working with notebooks

Install Jupyter if needed:

pip install jupyter
jupyter notebook

Then open any notebook in notebooks/.

A good beginner path is:

1. simulation_study.ipynb
2. Simulator_Thesis_Final.ipynb
3. Analysis_Thesis_Final.ipynb

The PDFs of above mentioned notebooks with cell captions can be found in the same folder for better understanding.

Running the real-data filter

The batch scripts are:

scripts/filter_v10.py
scripts/filter_v10_mode.py

1. filter_v10.py runs the original real-data pipeline.
2. filter_v10_mode.py adds selectable decision modes: v9 (statistical-only), v10c (Chapman-only) and v10 (Combined statistical + Chapman filtering)

Both scripts expect a directory of NetCDF profile files. By default, the repository includes an empty placeholder folder here:

data/real_iro/

You can place your files there or point the script to another directory.

macOS or Linux

python scripts/filter_v10.py --data-dir ./data/real_iro --out-root ./outputs

python scripts/filter_v10_mode.py --data-dir ./data/real_iro --out-root ./outputs_v9 --mode v9
python scripts/filter_v10_mode.py --data-dir ./data/real_iro --out-root ./outputs_v10 --mode v10
python scripts/filter_v10_mode.py --data-dir ./data/real_iro --out-root ./outputs_v10c --mode v10c

Windows PowerShell

python scripts/filter_v10.py --data-dir .\data\real_iro --out-root .\outputs

python scripts/filter_v10_mode.py --data-dir .\data\real_iro --out-root .\outputs_v9 --mode v9
python scripts/filter_v10_mode.py --data-dir .\data\real_iro --out-root .\outputs_v10 --mode v10
python scripts/filter_v10_mode.py --data-dir .\data\real_iro --out-root .\outputs_v10c --mode v10c

Optional filename controls

If your filenames follow a different pattern, you can also set:

--file-prefix ionPrf_ --file-suffix _nc

Downloading data from CDAAC

This repository works with COSMIC/CDAAC ionPrf NetCDF profile files.

What to download

Download Level 2 ionospheric profile files in ionPrf format.

Typical filenames look like:

ionPrf_IIII.YYYY.DDD.HH.MM.GGG_SSSS.VVVV_nc

Where to get the data

For official COSMIC GNSS radio occultation data, use the CDAAC archive from UCAR.

COSMIC-1

Use COSMIC-1 if you want historical mission data and reprocessed archives.

Archive root:

https://data.cosmic.ucar.edu/gnss-ro/cosmic1/

COSMIC-2

Use COSMIC-2 if you want newer ionospheric profiles.

Archive root:

https://data.cosmic.ucar.edu/gnss-ro/cosmic2/provisional/spaceWeather/

What to do after downloading

1. Download the ionPrf files you need.
2. Put them into:

data/real_iro/

3. Run the filter script:

python scripts/filter_v10.py --data-dir ./data/real_iro --out-root ./outputs

Notes

• Make sure you download ionPrf files specifically, not other product types such as atmPrf or wetPrf.
• data/real_iro/ is only a placeholder folder in this repository. You add the real NetCDF files yourself locally.
• If your downloaded filenames use a slightly different naming pattern, use --file-prefix and --file-suffix when running the script.

What the filter writes

scripts/filter_v10.py

A typical run can produce:

• iro_summary_v10.csv
• iro_failed_v10_profiles.csv
• iro_v9pass_v10fail_profiles.csv
• filtered_profiles_npz/
• failed_profiles_plots_v10/
• passed_profiles_plots_v10/
• v9pass_v10fail_plots/
• figures/

scripts/filter_v10_mode.py

A mode-selectable run writes outputs specific to the selected mode.

For --mode v9:

• iro_summary_v9.csv
• filtered_profiles_npz_v9/
• failed_profiles_plots_v9/
• passed_profiles_plots_v9/
• figures_v9/

For --mode v10:

• iro_summary_v10.csv
• filtered_profiles_npz_v10/
• failed_profiles_plots_v10/
• passed_profiles_plots_v10/
• figures_v10/

For --mode v10c:

• iro_summary_v10c.csv
• filtered_profiles_npz_v10c/
• failed_profiles_plots_v10c/
• passed_profiles_plots_v10c/
• figures_v10c/

Beginner questions

Where do I put my data?

Put real NetCDF input files in data/real_iro/, and/or point --data-dir to any other folder.

What kind of files does the script expect?

The filtering script is built for COSMIC-style ionPrf NetCDF profile files.

Do I need the thesis to use the code?

No. The repository is usable on its own.

The thesis gives the scientific background, design logic and validation context, but a new user can start directly with the example script and notebooks.

Are the large datasets included?

No. The repository is intentionally kept lightweight. Add your own real data locally.

Typical workflow

1. install the package
2. run the demo script
3. explore the notebooks
4. test simulation settings
5. download ionPrf data from CDAAC
6. run scripts/filter_v10.py or scripts/filter_v10_mode.py
7. inspect mode-specific CSV summaries and figures
8. use the cleaned outputs for downstream modelling or analysis

Common setup issues

If you run into environment or notebook errors, see:

TROUBLESHOOTING.md

Research context

This repository accompanies the Master's thesis done by Swaraj Bhosale at DGFI-TUM titled:

Analysis and Filtering of Ionospheric Radio Occultation Measurements for Modelling Purposes

The codebase reflects the practical software side of that work:

• simulation of controlled good and corrupted profiles
• evaluation of filtering logic
• comparison of statistical and Chapman-based checks
• application to real COSMIC-style data

For a public GitHub audience, the repository is intentionally organised as a usable software project first and a thesis companion second.

Citation

If you use this repository in academic work, please cite the repository and the associated Master's thesis.

A machine-readable citation file is included in:

CITATION.cff

Contributing

Suggestions, bug reports and cleanup improvements are welcome.

See:

CONTRIBUTING.md

License

MIT