MISA-XGModel


NameMISA-XGModel JSON
Version 0.2.1 PyPI version JSON
download
home_pagehttps://github.com/mcardonaserrano/MISA_XGModel
SummaryA Python library for predicting electron density using XGBoost
upload_time2024-12-04 08:04:32
maintainerNone
docs_urlNone
authorMateo Cardona Serrano
requires_python>=3.7
licenseNone
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # **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(
    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**

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/ce/04/6e1ae62711669fd8b4016f74cdeb3b6fb41a738ed2729fea0b4a0889fe5e/misa_xgmodel-0.2.1.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    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\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.1",
    "project_urls": {
        "Homepage": "https://github.com/mcardonaserrano/MISA_XGModel"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "b66d66dacf669c30cc1eefd7fc33bb2ea6f6ff1ccb37e44b278e703f84226cb8",
                "md5": "b3d96285faa75366db6208e35545776c",
                "sha256": "f94c8e7cb19036eba6e4e7ecda331d3c635acf213383422efbe12886b89e8d7c"
            },
            "downloads": -1,
            "filename": "MISA_XGModel-0.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "b3d96285faa75366db6208e35545776c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 9585,
            "upload_time": "2024-12-04T08:04:31",
            "upload_time_iso_8601": "2024-12-04T08:04:31.158340Z",
            "url": "https://files.pythonhosted.org/packages/b6/6d/66dacf669c30cc1eefd7fc33bb2ea6f6ff1ccb37e44b278e703f84226cb8/MISA_XGModel-0.2.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "ce046e1ae62711669fd8b4016f74cdeb3b6fb41a738ed2729fea0b4a0889fe5e",
                "md5": "d73c1f12e9c0032adf633b953c19c695",
                "sha256": "8a434f9ee0bdacf86e62ad95a43996a671919022fe7cedc5a31d05c9eae5c1e6"
            },
            "downloads": -1,
            "filename": "misa_xgmodel-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "d73c1f12e9c0032adf633b953c19c695",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 9318,
            "upload_time": "2024-12-04T08:04:32",
            "upload_time_iso_8601": "2024-12-04T08:04:32.172229Z",
            "url": "https://files.pythonhosted.org/packages/ce/04/6e1ae62711669fd8b4016f74cdeb3b6fb41a738ed2729fea0b4a0889fe5e/misa_xgmodel-0.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-12-04 08:04:32",
    "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"
}
        
Elapsed time: 0.40717s