<p align="center"> <img width="500" src="https://github.com/JouleCai/geospacelab/blob/master/docs/images/logo_v1_landscape_accent_colors.png"> </p>

GeospaceLAB (geospacelab)

GeospaceLAB provides a framework of data access, analysis, and visualization for the researchers in space physics and space weather. The documentation can be found on readthedocs.io.

Features

• Class-based data manager, including
  • DataHub: the core module (top-level class) to manage data from multiple sources,
  • Dataset: the middle-level class to download, load, and process data from a data source,
  • Variable: the base-level class to store the data array of a variable with various attributes, including its error, name, label, unit, group, and dependencies.
• Extendable
  • Provide a standard procedure from downloading, loading, and post-processing the data.
  • Easy to extend for a data source which has not been supported in the package.
  • Flexible to add functions for post-processing.
• Visualization
  • Time series plots with
    • automatically adjustable time ticks and tick labels.
    • dynamical panels (flexible to add or remove panels).
    • automatically detect the time gaps.
    • useful marking tools (vertical line crossing panels, shadings, top bars, etc, see Example 2 in Usage)
  • Map projection
    • Polar views with
      • coastlines in either GEO or AACGM (APEX) coordinate system.
      • mapping in either fixed lon/mlon mode or in fixed LST/MLT mode.
    • Support 1-D or 2-D plots with
      • satellite tracks (time ticks and labels)
      • nadir colored 1-D plots
      • gridded surface plots
• Space coordinate system transformation
  • Unified interface for cs transformations.
• Toolboxes for data analysis
  • Basic toolboxes for numpy array, datetime, logging, python dict, list, and class.

Built-in data sources:

| Data Source | Variables | File Format | Downloadable | Express | Status | |------------------------------|------------------------------------|-----------------------|---------------|-------------------------------|--------| | CDAWeb/OMNI | Solar wind and IMF |cdf | True | OMNIDashboard | stable | | CDAWeb/DMSP/SSUSI/EDR_AUR | DMSP SSUSI EDR_AUR emission lines | netcdf | True | DMSPSSUSIDashboard | stable | | Madrigal/EISCAT | Ionospheric Ne, Te, Ti, ... | EISCAT-hdf5, Madrigal-hdf5 | True | EISCATDashboard | stable | | Madrigal/GNSS/TECMAP | Ionospheric GPS TEC map | hdf5 | True | - | beta | | Madrigal/DMSP/s1 | DMSP SSM, SSIES, etc | hdf5 | True | DMSPTSDashboard | stable | | Madrigal/DMSP/s4 | DMSP SSIES | hdf5 | True | DMSPTSDashboard | stable | | Madrigal/DMSP/e | DMSP SSJ | hdf5 | True | DMSPTSDashboard | stable | | Madrigal/Millstone Hill ISR+ | Millstone Hill ISR | hdf5 | True | MillstoneHillISRDashboard | stable | | Madrigal/Poker Flat ISR | Poker Flat ISR | hdf5 | True | _- | stable | | JHUAPL/AMPERE/fitted | AMPERE FAC | netcdf | False | AMPEREDashboard | stable | | SuperDARN/POTMAP | SuperDARN potential map | ascii | False | - | stable |
| WDC/Dst | Dst index | IAGA2002-ASCII | True | - | stable | | WDC/ASYSYM | ASY/SYM indices | IAGA2002-ASCII | True | OMNIDashboard | stable | | WDC/AE | AE indices | IAGA2002-ASCII | True | OMNIDashboard | stable | | GFZ/Kp | Kp/Ap indices | ASCII | True | - | stable | | GFZ/Hpo | Hp30 or Hp60 indices | ASCII | True | - | stable | | GFZ/SNF107 | SN, F107 | ASCII | True | - | stable | | ESA/SWARM/EFI_LP_HM | SWARM Ne, Te, etc. | netcdf | True | - | stable | | ESA/SWARM/EFI_TCT02 | SWARM cross track vi | netcdf | True | - | stable | | ESA/SWARM/AOB_FAC_2F | SWARM FAC, auroral oval boundary | netcdf | True | - | beta | | TUDelft/SWARM/DNS_POD | Swarm $\rho_n$ (GPS derived) | ASCII | True | - | stable | | TUDelft/SWARM/DNS_ACC | Swarm $\rho_n$ (GPS+Accelerometer) | ASCII | True | - | stable | | TUDelft/GOCE/WIND_ACC | GOCE neutral wind | ASCII | True | - | stable | | TUDelft/GRACE/WIND_ACC | GRACE neutral wind | ASCII | True | - | stable | | TUDelft/GRACE/DNS_ACC | Grace $\rho_n$ | ASCII | True | - | stable | | TUDelft/CHAMP/DNS_ACC | CHAMP $\rho_n$ | ASCII | True | - | stable | | UTA/GITM/2DALL | GITM 2D output | binary, IDL-sav | False | - | beta | | UTA/GITM/3DALL | GITM 3D output | binary, IDL-sav | False | - | beta |

Installation

1. The python distribution "Anaconda" is recommended:

The package was tested with the anaconda distribution and with PYTHON>=3.7 under Ubuntu 20.04 and MacOS Big Sur.

With Anaconda, it may be easier to install some required dependencies listed below, e.g., cartopy, using the conda command. It's also recommended installing the package and dependencies in a virtual environment with anaconda.

After installing the anaconda distribution, a virtual environment can be created by the code below in the terminal:

conda create --name [YOUR_ENV_NAME] -c conda-forge python cython cartopy

The package "spyder" is a widely-used python IDE. Other IDEs, like "VS Code" or "Pycharm" also work.

Note: The recommended IDE is Spyder. Sometimes, a RuntimeError can be raised when the aacgmv2 package is called in PyCharm or VS Code. If you meet this issue, try to compile the codes in Spyder several times.

After creating the virtual environement, you need to activate the virtual environment:

conda activate [YOUR_ENV_NAME]

and then to install the package as shown below or to start the IDE Spyder.

More detailed information to set the anaconda environment can be found here,

2. Installation

Quick install from the pre-built release (recommended):

pip install geospacelab

Install from Github (not recommended):

pip install git+https://github.com/JouleCai/geospacelab@master

2. Dependencies

The package dependencies need to be installed before or after the installation of the package. Several dependencies will be installed automatically with the package installation, including toml, requests, bueatifulsoup4, numpy, scipy, matplotlib, h5py, netcdf4, cdflib, madrigalweb, sscws, and aacgmv2.

Other dependencies will be needed if you see a ImportError or ModuleNotFoundError displayed in the python console. Some frequently used modules and their installation methods are listed below:

• cartopy: Map projection for geospatial data.
  • conda install -c conda-forge cartopy
• apexpy *: Apex and Quasi-Dipole geomagnetic coordinate system.
  • pip install apexpy
• geopack: The geopack and Tsyganenko models in Python.
  • pip install geopack

(*): The gcc or gfortran compilers are required before installing the package.

• gcc: conda install -c conda-forge gcc
• gfortran: conda install -c conda-forge gfortran

Please install the packages above, if needed.

Note: The package is currently pre-released. The installation methods may b