Metadata-Version: 2.4
Name: ionotec
Version: 0.0.15
Summary: Code calculating TEC from RINEX information
Author-email: Sylvain Blunier <sylvain.blunier@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/sylvathle/ionotec
Project-URL: Issues, https://github.com/sylvathle/ionotec/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: georinex
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pymap3d
Requires-Dist: datetime
Requires-Dist: scipy
Requires-Dist: pyarrow
Requires-Dist: matplotlib
Requires-Dist: cartopy
Dynamic: license-file

# ionotec
Python library for Total Electron Content computing from GNSS Rinex files

## Requirements

Tested on Python 3.9.2

## Installation

```
pip install ionotec
```

### Known Errors

**Incompatible xarray module version with georinex**

Georinex has some specific dependencies that we have observed could be broken.
In particular latest versions of the "xarray" module are not compatible with georinex and might make the georinex "load" method fail.

A known solution is to force a working version of "xarray":

```bash
pip3 install xarray=0.20.1
```

**Other problems**

Please report problems you find to install ionotec to *sylvain.blunier@gmail.com*

## Code

### Loading module

To load the ionotec module, do:

`from ionotec import tec`

### Defining input data

Computing VTEC requires having the following elements:

1. A list Rinex observation file
This is the file list where the code and phase data will be extracted. The files will be concatenated in the process. They should come in continuous and chronological order. Also important, they should correspond to only one station; a further version will be able to process several stations at a time.
* Format: List of strings
* Example: `f_obs=["/home/me/ionotec/amtc1200.21o","/home/me/ionotec/amtc1210.21o","/home/me/ionotec/amtc1220.21o"]`

2. List of Rinex navigation files
This is the file list from which the positions of the satellites will be extracted, usually using a few well-chosen files, and the positions of all satellites can then be calculated. Of course, they should correspond to the observation periods in the files.
* Format: List of strings
* Example: `f_nav=["/home/me/ionotec/amtc1201.21n","/home/me/ionotec/amtc1211.21n","/home/me/ionotec/amtc1221.21n"]`

3. File containing satellites DCB, which can be retrieved from <https://cddis.nasa.gov/archive/gnss/products/bias/>
File containing the bias of satellites corresponding to the month of observation files
* Format: string pointing to DCB file, only one for the process.
* Example: `f_bias="/home/me/ionotec/CAS0MGXRAP_20203450000_01D_01D_DCB.bsx"`

We recommend informing one day before and after the period of interest to avoid border effects. 

### Computing VTEC

Once these elements are defined, an instance of ionotec can be created:

`station_tec = tec.tec(f_obs,f_nav,f_bias)`

And VTEC can be computed with default parameters:

`station_tec.compute_vtec()`

This will create one file in *feather* format in the same path as the second item of `f_obs`, or the first one in case `f_obs` is a one-item list, so in the case of the variables defined upper the files should be found at `/home/me/ionotec/amtc121-tec.feather`.
This will create a folder structure in the same place where the script is run. The tree will look like:
    
        output/
          |__ stations.csv
          |-- GNSS/
                |- 2020/
                    |__ G01.feather
                    |__      ...
                    |__ R24.feather
                |_ record_processing.csv                
          |-- TEC/
                |- 2020/
                    |__ sta1.feather
                    |__      ...
                    |__ staN.feather
                    |__ receiver_bias.csv
          

* GNSS contains essentially the GNSS position of the satellites (X,Y,Z) for the timeframes informed in the `f_nav` list. The purpose of the file record_processing is to keep track of the days that were processed, for each constellation and inform the best time resolution processed so far. This avoids reprocessing.

* TEC contains the produced TEC information with a naming format XXXX.feather, where XXXX corresponds to the 4 characters labelling the receiver. 
It will contain the following information:

* **time** (string): *YYYY-MM-DD HH:mm:ss* format
* **sv** (string): satellite from which the VTEC is calculated
* **lat** (float): latitude of calculated piercing point
* **lon** (float):  longitude of calculated piercing point
* **elevation** (float): elevation of satellite in Radians
* **STEC_slp** (float): slant TEC in TEC Units calculated with pseudo range (P1 and C1 in rinex observation files)
* **STEC_sl** (float): slant TEC in TEC Units calculated with code phases (L1 and L2 in rinex observation files)
* **VTEC** (float): Vertical TEC in TEC Units, corrected with baseline, satellite bias, receiver bias.

The pandas DataFrame of this data can be directly accessed in the instanciated object through: `station_tec.df_obs`.
They can be loaded as posteriori using `df_station = pd.read_feather("output/TEC/YYYY/stat.feather")`

The file receiver_bias.csv contains the bias information for each processed station.

* stations.csv contains the information on the position of each processed station (should probably be merged with receiver_bias.csv in the future)

### Plots

Quick PNGs of data can be directly produced using the `ionotec.graph` submodule:

```
from ionotec import graph
```

All satellites in one graph
```
graph.plot_station(station_tec.df_obs)
```

or 8 satellites per graph in a mosaic fashion
```
graph.plot_station(station_tec.df_obs,mozaic=True)
```

These graphs will be generated in `output/TEC/Figs/`.

