| Name | PyVALION JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Python Validation Tool for the Ionosphere |
| upload_time | 2025-10-29 22:33:24 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2023 victoriyaforsythe
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
ionosphere
modeling
modelling
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<img width="200" height="200" src="https://github.com/victoriyaforsythe/PyVALION/blob/main/docs/figures/PyVALION_logo.png" alt="Black circle with lion ionospheric vertical profile" title="PyVALION Logo" style="float:left;">
# PyVALION (Python VALidation for IONosphere)
[](https://pypi.org/project/PyVALION/)
[](https://github.com/victoriyaforsythe/PyVALION/actions/workflows/main.yml)
[](https://pyvalion.readthedocs.io/en/latest/?badge=latest)
[](https://doi.org/10.5281/zenodo.15413125)
PyVALION is a Python-based software package for validating ionospheric electron density model outputs.
For a given day, it downloads ionospheric parameters (such as NmF2, hmF2, B0, and B1) from the Global Ionosphere Radio Observatory (GIRO) and constructs a forward operator (geometry matrix) to compute the model-expected observations. It then calculates residuals between the observed ionospheric parameters and the model predictions and provides visual diagnostics.
A key advantage of PyVALION is its efficiency: if you need to validate multiple model runs on the same grid, the geometry matrix only needs to be computed once. This significantly speeds up and simplifies the validation process.
If you're validating your model across multiple days, you can run PyVALION in a loop and concatenate the residuals into 1-D arrays for broader analysis.
# Installation
PyVALION can be installed from PyPI, which handles all dependencies:
```
pip install PyVALION
```
Alternatively, you can clone and install it from GitHub:
```
git clone https://github.com/victoriyaforsythe/PyVALION.git
cd PyVALION
pip install .
```
See the documentation for details about the required dependencies.
# Example Workflow for GIRO Parameter Validation
1. Create the model output dictionary: Record your model output into a dictionary called model with the following keys: 'NmF2', 'hmF2', 'B0', and 'B1', shaped as [N_time, N_lat, N_lon].
N_time: number of time steps (e.g., 96 for 15-minute resolution)
N_lat: number of geographic latitudes
N_lon: number of geographic longitudes
All arrays must have the same shape. Otherwise, the forward operator G cannot be applied consistently.
2. Define the units dictionary:
```
units = {'NmF2': 'm$^{-3}$', 'hmF2': 'km', 'B0': 'km', 'B1': ' '}
```
Ensure your model output is in these units.
3. Create the atime array: This array should have N_time elements and must be a list of datetime objects that match the time dimension of your model dictionary. Example for 15-minute resolution:
```
dtime = datetime.datetime(year, month, day)
atime = pd.to_datetime(np.arange(dtime,
dtime + datetime.timedelta(days=1),
datetime.timedelta(minutes=15)))
```
4. Define the latitude array alat: This array must have N_lat elements and match the second dimension in the model dictionary.
5. Define the longitude array alon: This array must have N_lon elements and match the third dimension in the model dictionary.
6. Load the list of GIRO ionosondes:
```
file_ion_name = os.path.join(PyVALION.giro_names_dir, 'GIRO_Ionosondes.p')
giro_name = pickle.load(open(file_ion_name, 'rb'))
```
If you wish to exclude ionosondes used in your data assimilation, simply modify the giro_name['name'] array.
7. Download GIRO parameters:
```
raw_data = PyVALION.library.download_GIRO_parameters(atime[0],
atime[-1],
giro_name['name'],
data_save_dir,
save_res_dir,
name_run,
clean_directory=True,
filter_CS=90)
```
data_save_dir: path to save downloaded data
save_res_dir: path to save processed results
name_run: your chosen name for this run
8. Create the forward operator:
```
obs_data, obs_units, G, obs_info = PyVALION.library.find_G_and_y(atime,
alon,
alat,
raw_data,
save_res_dir,
name_run,
True)
```
9. Compute residuals:
```
model_data, residuals, model_units, res_ion = PyVALION.library.find_residuals(
model, G, obs_data, obs_info, units)
```
10. Plot results:
```
# Map of ionosonde locations
PyVALION.plotting.plot_ionosondes(obs_info,
dtime,
save_res_dir,
plot_name='Ionosondes_Map.pdf')
```
# Histogram of residuals
```
PyVALION.plotting.plot_histogram(residuals,
model_units,
dtime,
save_res_dir,
plot_name='Residuals.pdf')
```
# Mean residuals for each ionosonde
```
PyVALION.plotting.plot_individual_mean_residuals(res_ion,
obs_info,
model_units,
dtime,
save_res_dir,
plot_name='IonRes.pdf')
```
# Example Workflow for Jason TEC Validation
1. Create the model output dictionary: Record your model output into a dictionary called model with the following key: 'TEC' shaped as [N_time, N_lat, N_lon].
N_time: number of time steps (e.g., 96 for 15-minute resolution)
N_lat: number of geographic latitudes
N_lon: number of geographic longitudes
2. Define the units dictionary:
```
units = {'TEC': 'TECU'}
```
Ensure your model output is in these units.
3. Create the atime array: This array should have N_time elements and must be a list of datetime objects that match the time dimension of your model dictionary. Example for 15-minute resolution:
```
dtime = datetime.datetime(year, month, day)
atime = pd.to_datetime(np.arange(dtime,
dtime + datetime.timedelta(days=1),
datetime.timedelta(minutes=15)))
```
4. Define the latitude array alat: This array must have N_lat elements and match the second dimension in the model dictionary.
5. Define the longitude array alon: This array must have N_lon elements and match the third dimension in the model dictionary.
6. Download the jason_manifest.txt file (provided by PyVALION) and save locally into data_save_dir. The local manifest will be updated with new THREDDS file locations if available.
data_save_dir: path to save downloaded data
7. Download all raw Jason TEC data for the validation time: If you need to exclude certain satellites, modify the sat_names array.
```
sat_names = np.array(["JA2", "JA3"])
raw_data = PyVALION.library.download_Jason_TEC(atime[0],
atime[-1],
data_save_dir,
name_run=name_run,
save_data_option=True,
sat_names=sat_names)
```
data_save_dir: path to save downloaded data
name_run: your chosen name for this run
8. Downsample Jason TEC data to match model resolution:
```
data = PyVALION.library.downsample_Jason_TEC(raw_data,
ddeg,
save_dir=data_save_dir,
name_run=name_run,
save_data_option=True)
```
9. Create a forward operator for the Jason TEC dataset using the given model grid:
```
obs_data, obs_units, G = PyVALION.library.find_Jason_G_and_y(atime,
alon,
alat,
data)
```
10. Compute residuals:
```
model_data, residuals, model_units = PyVALION.library.find_Jason_residuals(model,
G,
obs_data,
units)
```
11. Plot results:
# Map of residuals
```
PyVALION.plotting.plot_TEC_residuals_map(obs_data['lat'],
obs_data['lon'],
residuals,
atime[0],
save_option=True,
save_dir=save_img_dir,
plot_name='TEC_Residuals_Map')
```
# Histogram of residuals
```
PyVALION.plotting.plot_TEC_residuals_histogram(residuals,
model_units,
atime[0],
save_option=True,
save_dir=save_img_dir,
plot_name='TEC_Residuals')
```
# Learn More
See the [tutorials](https://github.com/victoriyaforsythe/PyVALION/tree/main/docs/tutorials) folder for examples that validate NmF2, hmF2, and TEC from [PyIRI](https://github.com/victoriyaforsythe/PyIRI).
Raw data
{
"_id": null,
"home_page": null,
"name": "PyVALION",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ionosphere, modeling, modelling",
"author": null,
"author_email": "Victoriya Forsythe <victoriya.v.makarevich.civ@us.navy.mil>",
"download_url": "https://files.pythonhosted.org/packages/a7/a7/726f6dcd60d5065e751403e637a757114843cafd4b4a79a38413c4fbf146/pyvalion-0.1.0.tar.gz",
"platform": null,
"description": "<img width=\"200\" height=\"200\" src=\"https://github.com/victoriyaforsythe/PyVALION/blob/main/docs/figures/PyVALION_logo.png\" alt=\"Black circle with lion ionospheric vertical profile\" title=\"PyVALION Logo\" style=\"float:left;\">\n\n\n# PyVALION (Python VALidation for IONosphere)\n[](https://pypi.org/project/PyVALION/)\n[](https://github.com/victoriyaforsythe/PyVALION/actions/workflows/main.yml)\n[](https://pyvalion.readthedocs.io/en/latest/?badge=latest)\n[](https://doi.org/10.5281/zenodo.15413125)\n\nPyVALION is a Python-based software package for validating ionospheric electron density model outputs.\n\nFor a given day, it downloads ionospheric parameters (such as NmF2, hmF2, B0, and B1) from the Global Ionosphere Radio Observatory (GIRO) and constructs a forward operator (geometry matrix) to compute the model-expected observations. It then calculates residuals between the observed ionospheric parameters and the model predictions and provides visual diagnostics.\n\nA key advantage of PyVALION is its efficiency: if you need to validate multiple model runs on the same grid, the geometry matrix only needs to be computed once. This significantly speeds up and simplifies the validation process.\n\nIf you're validating your model across multiple days, you can run PyVALION in a loop and concatenate the residuals into 1-D arrays for broader analysis.\n\n\n# Installation\n\nPyVALION can be installed from PyPI, which handles all dependencies:\n\n```\npip install PyVALION\n```\n\nAlternatively, you can clone and install it from GitHub:\n\n```\ngit clone https://github.com/victoriyaforsythe/PyVALION.git\ncd PyVALION\npip install .\n```\n\nSee the documentation for details about the required dependencies.\n\n# Example Workflow for GIRO Parameter Validation\n\n1. Create the model output dictionary: Record your model output into a dictionary called model with the following keys: 'NmF2', 'hmF2', 'B0', and 'B1', shaped as [N_time, N_lat, N_lon].\n\nN_time: number of time steps (e.g., 96 for 15-minute resolution)\n\nN_lat: number of geographic latitudes\n\nN_lon: number of geographic longitudes\n\nAll arrays must have the same shape. Otherwise, the forward operator G cannot be applied consistently.\n\n2. Define the units dictionary:\n\n```\nunits = {'NmF2': 'm$^{-3}$', 'hmF2': 'km', 'B0': 'km', 'B1': ' '}\n```\nEnsure your model output is in these units.\n\n3. Create the atime array: This array should have N_time elements and must be a list of datetime objects that match the time dimension of your model dictionary. Example for 15-minute resolution:\n\n```\ndtime = datetime.datetime(year, month, day)\natime = pd.to_datetime(np.arange(dtime,\n dtime + datetime.timedelta(days=1),\n datetime.timedelta(minutes=15)))\n```\n\n4. Define the latitude array alat: This array must have N_lat elements and match the second dimension in the model dictionary.\n\n5. Define the longitude array alon: This array must have N_lon elements and match the third dimension in the model dictionary.\n\n6. Load the list of GIRO ionosondes:\n\n```\nfile_ion_name = os.path.join(PyVALION.giro_names_dir, 'GIRO_Ionosondes.p')\ngiro_name = pickle.load(open(file_ion_name, 'rb'))\n```\n\nIf you wish to exclude ionosondes used in your data assimilation, simply modify the giro_name['name'] array.\n\n7. Download GIRO parameters:\n\n```\nraw_data = PyVALION.library.download_GIRO_parameters(atime[0],\n atime[-1],\n giro_name['name'],\n data_save_dir,\n save_res_dir,\n name_run,\n clean_directory=True,\n filter_CS=90)\n```\n\ndata_save_dir: path to save downloaded data\n\nsave_res_dir: path to save processed results\n\nname_run: your chosen name for this run\n\n8. Create the forward operator:\n```\nobs_data, obs_units, G, obs_info = PyVALION.library.find_G_and_y(atime,\n alon,\n alat,\n raw_data,\n save_res_dir,\n name_run,\n True)\n```\n\n9. Compute residuals:\n\n```\nmodel_data, residuals, model_units, res_ion = PyVALION.library.find_residuals(\n model, G, obs_data, obs_info, units)\n```\n\n10. Plot results:\n```\n# Map of ionosonde locations\nPyVALION.plotting.plot_ionosondes(obs_info,\n dtime,\n save_res_dir,\n plot_name='Ionosondes_Map.pdf')\n```\n\n\n# Histogram of residuals\n```\nPyVALION.plotting.plot_histogram(residuals,\n model_units,\n dtime,\n save_res_dir,\n plot_name='Residuals.pdf')\n```\n\n\n\n# Mean residuals for each ionosonde\n```\nPyVALION.plotting.plot_individual_mean_residuals(res_ion,\n obs_info,\n model_units,\n dtime,\n save_res_dir,\n plot_name='IonRes.pdf')\n```\n\n\n\n\n\n# Example Workflow for Jason TEC Validation\n\n\n1. Create the model output dictionary: Record your model output into a dictionary called model with the following key: 'TEC' shaped as [N_time, N_lat, N_lon].\n\nN_time: number of time steps (e.g., 96 for 15-minute resolution)\n\nN_lat: number of geographic latitudes\n\nN_lon: number of geographic longitudes\n\n2. Define the units dictionary:\n\n```\nunits = {'TEC': 'TECU'}\n```\nEnsure your model output is in these units.\n\n3. Create the atime array: This array should have N_time elements and must be a list of datetime objects that match the time dimension of your model dictionary. Example for 15-minute resolution:\n\n```\ndtime = datetime.datetime(year, month, day)\natime = pd.to_datetime(np.arange(dtime,\n dtime + datetime.timedelta(days=1),\n datetime.timedelta(minutes=15)))\n```\n\n4. Define the latitude array alat: This array must have N_lat elements and match the second dimension in the model dictionary.\n\n5. Define the longitude array alon: This array must have N_lon elements and match the third dimension in the model dictionary.\n\n6. Download the jason_manifest.txt file (provided by PyVALION) and save locally into data_save_dir. The local manifest will be updated with new THREDDS file locations if available.\n\ndata_save_dir: path to save downloaded data\n\n7. Download all raw Jason TEC data for the validation time: If you need to exclude certain satellites, modify the sat_names array.\n\n```\nsat_names = np.array([\"JA2\", \"JA3\"])\nraw_data = PyVALION.library.download_Jason_TEC(atime[0],\n atime[-1],\n data_save_dir,\n name_run=name_run,\n save_data_option=True,\n sat_names=sat_names)\n```\n\ndata_save_dir: path to save downloaded data\n\nname_run: your chosen name for this run\n\n8. Downsample Jason TEC data to match model resolution:\n\n```\ndata = PyVALION.library.downsample_Jason_TEC(raw_data,\n ddeg,\n save_dir=data_save_dir,\n name_run=name_run,\n save_data_option=True)\n```\n\n9. Create a forward operator for the Jason TEC dataset using the given model grid:\n\n```\nobs_data, obs_units, G = PyVALION.library.find_Jason_G_and_y(atime,\n alon,\n alat,\n data)\n```\n\n10. Compute residuals:\n\n```\nmodel_data, residuals, model_units = PyVALION.library.find_Jason_residuals(model,\n G,\n obs_data,\n units)\n```\n\n11. Plot results:\n\n# Map of residuals\n```\nPyVALION.plotting.plot_TEC_residuals_map(obs_data['lat'],\n obs_data['lon'],\n residuals,\n atime[0],\n save_option=True,\n save_dir=save_img_dir,\n plot_name='TEC_Residuals_Map')\n```\n\n\n# Histogram of residuals\n```\nPyVALION.plotting.plot_TEC_residuals_histogram(residuals,\n model_units,\n atime[0],\n save_option=True,\n save_dir=save_img_dir,\n plot_name='TEC_Residuals')\n```\n\n\n\n# Learn More\n\nSee the [tutorials](https://github.com/victoriyaforsythe/PyVALION/tree/main/docs/tutorials) folder for examples that validate NmF2, hmF2, and TEC from [PyIRI](https://github.com/victoriyaforsythe/PyIRI).\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2023 victoriyaforsythe\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Python Validation Tool for the Ionosphere",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://pyvalion.readthedocs.io/en/latest/",
"Source": "https://github.com/victoriyaforsythe/PyVALION"
},
"split_keywords": [
"ionosphere",
" modeling",
" modelling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "65fe485e047f1c0ff73dbffd37342c14b4d83cf289aec657b5b8e76b2bcbf473",
"md5": "718dd25c15462cf39489bf83acfbf02e",
"sha256": "e3f5e9f47d89bd83fc0675bac079bf0b2053b89dbd1795af8b7d925d994b78be"
},
"downloads": -1,
"filename": "pyvalion-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "718dd25c15462cf39489bf83acfbf02e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 29697,
"upload_time": "2025-10-29T22:33:23",
"upload_time_iso_8601": "2025-10-29T22:33:23.367792Z",
"url": "https://files.pythonhosted.org/packages/65/fe/485e047f1c0ff73dbffd37342c14b4d83cf289aec657b5b8e76b2bcbf473/pyvalion-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a7a7726f6dcd60d5065e751403e637a757114843cafd4b4a79a38413c4fbf146",
"md5": "204af88b5db2ae4b1a3784ebe2e57090",
"sha256": "f72aaa1aefb8021c70fcf69ae33b5f79234c40959bf6336ff3a6b43799f2a054"
},
"downloads": -1,
"filename": "pyvalion-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "204af88b5db2ae4b1a3784ebe2e57090",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 39109,
"upload_time": "2025-10-29T22:33:24",
"upload_time_iso_8601": "2025-10-29T22:33:24.540928Z",
"url": "https://files.pythonhosted.org/packages/a7/a7/726f6dcd60d5065e751403e637a757114843cafd4b4a79a38413c4fbf146/pyvalion-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 22:33:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "victoriyaforsythe",
"github_project": "PyVALION",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyvalion"
}
