# **MISA_XGModel**
*A Python library for predicting electron density using XGBoost.*
---
## **Overview**
This library provides tools to predict electron density (`Ne`) using a machine-learning model based on XGBoost. It supports querying predictions for specific latitude, longitude, day of year (DOY), altitude, and solar local time (SLT), while leveraging pre-computed geophysical indices. The library also supports efficient vectorized predictions for multiple inputs.
---
## **Features**
- Predict electron density (`Ne`) for specific geospatial and temporal conditions.
- Efficient batch predictions using vectorized input arrays for higher performance.
- Clamp or wrap input values to the bounds of the training dataset for robustness.
- Supports querying geophysical indices from provided datasets.
- Modular design for integrating geophysical models in Python applications.
---
## **Installation**
You can install this package via **pip**:
```bash
pip install MISA_XGModel
```
The model downloads missing dependencies on first import (e.g., the XGBoost model weights, scaler, and geophysical dataset):
```bash
Downloading model from https://www.dropbox.com/...
Model downloaded and saved to data/xgboost_optimized_model.json.
Downloading scaler from https://www.dropbox.com/...
Scaler downloaded and saved to data/scaler_large.json.
Downloading dataset from https://www.dropbox.com/...
Dataset downloaded and saved to data/master_geo_ds.nc.
```
If the files already exist locally, the library will skip the download step and use the existing files.
---
## **Usage**
### **Quickstart**
Here’s how you can use the library to predict electron density:
#### **Single Prediction**
```python
from MISA_XGModel import predict_ne, query_model
# Predict Ne with dataset lookup for geophysical indices
predicted_ne = predict_ne(
lat=42.0, lon=-71.0, doy=99, alt=150.0, slt=12.0, year=2024
)
print(f"Predicted Ne: {predicted_ne:.2e}")
# Predict Ne with precomputed geophysical indices
predicted_ne = query_model(
lat=42.0, lon=-71.0, doy=99, alt=150.0, slt=12.0,
hp30=2, ap30=7, f107=209, kp=2.3, fism2=0.0007678
)
print(f"Predicted Ne: {predicted_ne:.2e}")
```
#### **Batch Predictions**
To predict multiple inputs efficiently, you can pass arrays to `predict_ne` or `query_model`:
```python
import numpy as np
# Vectorized inputs
lats = np.array([42.0, 41.5, 40.0])
lons = np.array([-71.0, -72.0, -73.0])
doys = np.array([99, 100, 101])
alts = np.array([150.0, 200.0, 250.0])
slts = np.array([12.0, 14.0, 16.0])
year = 2024
# Batch predict Ne with dataset lookup for geophysical indices
predicted_ne = predict_ne(
lat=lats, lon=lons, doy=doys, alt=alts, slt=slts, year=year
)
print(f"Predicted Ne: {predicted_ne}")
# Batch predict Ne with precomputed geophysical indices
predicted_ne = query_model(
verbose=True, lat=lats, lon=lons, doy=doys, alt=alts, slt=slts,
hp30=np.array([2, 3, 4]),
ap30=np.array([7, 8, 9]),
f107=np.array([209, 210, 211]),
kp=np.array([2.3, 2.5, 2.7]),
fism2=np.array([0.0007678, 0.00078, 0.00079])
)
print(f"Predicted Ne: {predicted_ne}")
```
---
## **Inputs and Parameters**
### **Clamping and Wrapping Input Values**
Set argument `verbose=True` to enable progress bar.
Input parameters (`lat`, `lon`, `alt`, `slt`) are clamped to the boundaries of the training data, while `doy` is wrapped to stay within `[0, 364]`. These boundaries are defined as follows:
| Parameter | Min Value | Max Value | Notes |
|-----------|-----------|-----------|-----------------------------------------|
| `lat` | 37.5 | 49.9 | Clamped to range |
| `lon` | -85.7 | -76.1 | Clamped to range |
| `alt` | 94.6 km | 500 km | Clamped to range |
| `slt` | 0.0 hrs | 24 hrs | Clamped to range |
| `doy` | 0 | 364 | Wrapped (e.g., `365 → 0`, `-1 → 364`) |
---
## **Requirements**
- Python 3.7+
- **Dependencies**:
- `xgboost`
- `scikit-learn`
- `numpy`
- `pandas`
- `xarray`
- `joblib`
- `netcdf4`
---
## **License**
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## **Author**
- **Mateo Cardona Serrano (them)**
- [GitHub Profile](https://github.com/mcardonaserrano)
- [Email](mailto:mcardonaserrano@berkeley.edu)
---
## **Acknowledgments**
- Thank you to Sevag Derghazarian for his continuous support and consultation on this project.
---
Raw data
{
"_id": null,
"home_page": "https://github.com/mcardonaserrano/MISA_XGModel",
"name": "MISA-XGModel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "Mateo Cardona Serrano",
"author_email": "mcardonaserrano@berkeley.edu",
"download_url": "https://files.pythonhosted.org/packages/68/a7/bdbf37392ba2627a1cad61e590ea8e08bcef7b295a7255f788b2b45c5f37/misa_xgmodel-0.2.5.tar.gz",
"platform": null,
"description": "# **MISA_XGModel** \n*A Python library for predicting electron density using XGBoost.*\n\n---\n## **Overview** \n\nThis library provides tools to predict electron density (`Ne`) using a machine-learning model based on XGBoost. It supports querying predictions for specific latitude, longitude, day of year (DOY), altitude, and solar local time (SLT), while leveraging pre-computed geophysical indices. The library also supports efficient vectorized predictions for multiple inputs.\n\n---\n\n## **Features** \n- Predict electron density (`Ne`) for specific geospatial and temporal conditions.\n- Efficient batch predictions using vectorized input arrays for higher performance.\n- Clamp or wrap input values to the bounds of the training dataset for robustness.\n- Supports querying geophysical indices from provided datasets.\n- Modular design for integrating geophysical models in Python applications.\n\n---\n\n## **Installation** \n\nYou can install this package via **pip**:\n\n```bash\npip install MISA_XGModel\n```\n\n\n\nThe model downloads missing dependencies on first import (e.g., the XGBoost model weights, scaler, and geophysical dataset):\n```bash\nDownloading model from https://www.dropbox.com/...\nModel downloaded and saved to data/xgboost_optimized_model.json.\nDownloading scaler from https://www.dropbox.com/...\nScaler downloaded and saved to data/scaler_large.json.\nDownloading dataset from https://www.dropbox.com/...\nDataset downloaded and saved to data/master_geo_ds.nc.\n```\n\nIf the files already exist locally, the library will skip the download step and use the existing files.\n\n---\n\n## **Usage** \n\n### **Quickstart**\n\nHere\u2019s how you can use the library to predict electron density:\n\n#### **Single Prediction**\n\n```python\nfrom MISA_XGModel import predict_ne, query_model\n\n# Predict Ne with dataset lookup for geophysical indices\npredicted_ne = predict_ne(\n lat=42.0, lon=-71.0, doy=99, alt=150.0, slt=12.0, year=2024\n)\nprint(f\"Predicted Ne: {predicted_ne:.2e}\")\n\n# Predict Ne with precomputed geophysical indices\npredicted_ne = query_model(\n lat=42.0, lon=-71.0, doy=99, alt=150.0, slt=12.0,\n hp30=2, ap30=7, f107=209, kp=2.3, fism2=0.0007678\n)\nprint(f\"Predicted Ne: {predicted_ne:.2e}\")\n```\n\n#### **Batch Predictions**\n\nTo predict multiple inputs efficiently, you can pass arrays to `predict_ne` or `query_model`:\n\n```python\nimport numpy as np\n\n# Vectorized inputs\nlats = np.array([42.0, 41.5, 40.0])\nlons = np.array([-71.0, -72.0, -73.0])\ndoys = np.array([99, 100, 101])\nalts = np.array([150.0, 200.0, 250.0])\nslts = np.array([12.0, 14.0, 16.0])\nyear = 2024\n\n# Batch predict Ne with dataset lookup for geophysical indices\npredicted_ne = predict_ne(\n lat=lats, lon=lons, doy=doys, alt=alts, slt=slts, year=year\n)\nprint(f\"Predicted Ne: {predicted_ne}\")\n\n# Batch predict Ne with precomputed geophysical indices\npredicted_ne = query_model(\n verbose=True, lat=lats, lon=lons, doy=doys, alt=alts, slt=slts,\n hp30=np.array([2, 3, 4]),\n ap30=np.array([7, 8, 9]),\n f107=np.array([209, 210, 211]),\n kp=np.array([2.3, 2.5, 2.7]),\n fism2=np.array([0.0007678, 0.00078, 0.00079])\n)\nprint(f\"Predicted Ne: {predicted_ne}\")\n```\n\n---\n\n## **Inputs and Parameters**\n\n### **Clamping and Wrapping Input Values**\n\nSet argument `verbose=True` to enable progress bar.\n\nInput parameters (`lat`, `lon`, `alt`, `slt`) are clamped to the boundaries of the training data, while `doy` is wrapped to stay within `[0, 364]`. These boundaries are defined as follows:\n\n| Parameter | Min Value | Max Value | Notes |\n|-----------|-----------|-----------|-----------------------------------------|\n| `lat` | 37.5 | 49.9 | Clamped to range |\n| `lon` | -85.7 | -76.1 | Clamped to range |\n| `alt` | 94.6 km | 500 km | Clamped to range |\n| `slt` | 0.0 hrs | 24 hrs | Clamped to range |\n| `doy` | 0 | 364 | Wrapped (e.g., `365 \u2192 0`, `-1 \u2192 364`) |\n---\n\n## **Requirements**\n\n- Python 3.7+\n- **Dependencies**:\n - `xgboost`\n - `scikit-learn`\n - `numpy`\n - `pandas`\n - `xarray`\n - `joblib`\n - `netcdf4`\n\n---\n\n## **License** \n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## **Author** \n\n- **Mateo Cardona Serrano (them)** \n- [GitHub Profile](https://github.com/mcardonaserrano) \n- [Email](mailto:mcardonaserrano@berkeley.edu) \n\n---\n\n## **Acknowledgments** \n\n- Thank you to Sevag Derghazarian for his continuous support and consultation on this project. \n\n--- \n",
"bugtrack_url": null,
"license": null,
"summary": "A Python library for predicting electron density using XGBoost",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/mcardonaserrano/MISA_XGModel"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3f9d01e13bfc5dfddfaff19f44d4b6cb67f468d120ec4ff87b6c87ee266096d",
"md5": "079118444cd8b256d8ac618970644508",
"sha256": "8e8053ec11320f2c94eabbe64454ff1cadc9b1b9931513c51d1f3b7816fbd88d"
},
"downloads": -1,
"filename": "MISA_XGModel-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "079118444cd8b256d8ac618970644508",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8482,
"upload_time": "2024-12-08T02:12:45",
"upload_time_iso_8601": "2024-12-08T02:12:45.608753Z",
"url": "https://files.pythonhosted.org/packages/c3/f9/d01e13bfc5dfddfaff19f44d4b6cb67f468d120ec4ff87b6c87ee266096d/MISA_XGModel-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "68a7bdbf37392ba2627a1cad61e590ea8e08bcef7b295a7255f788b2b45c5f37",
"md5": "e9628eacc17dfbdbd005a83dee60f382",
"sha256": "94ea641fcc2f31890ef3d51de4d42987873997a0052e59d60c0d0e8fa5ee88dd"
},
"downloads": -1,
"filename": "misa_xgmodel-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "e9628eacc17dfbdbd005a83dee60f382",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8182,
"upload_time": "2024-12-08T02:12:47",
"upload_time_iso_8601": "2024-12-08T02:12:47.143011Z",
"url": "https://files.pythonhosted.org/packages/68/a7/bdbf37392ba2627a1cad61e590ea8e08bcef7b295a7255f788b2b45c5f37/misa_xgmodel-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-08 02:12:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mcardonaserrano",
"github_project": "MISA_XGModel",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "misa-xgmodel"
}
JSON
