Metadata-Version: 2.1
Name: ecallisto-ng
Version: 0.3.3
Summary: A Python package for the fetching (and some processing) of eCallisto data via the eCallisto API.
Author-email: Vincenzo Timmel <vincenzo.timmel@fhnw.ch>
Project-URL: Homepage, https://github.com/i4Ds/ecallisto_ng
Project-URL: Bug Tracker, https://github.com/i4Ds/ecallisto_ng/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy >=1.21.6
Requires-Dist: pandas >=2.0.0
Requires-Dist: plotly
Requires-Dist: matplotlib
Requires-Dist: requests
Requires-Dist: scikit-image >=0.20.0
Requires-Dist: pyarrow
Provides-Extra: dev
Requires-Dist: black ; extra == 'dev'
Requires-Dist: isort ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: build ; extra == 'dev'
Provides-Extra: nb
Requires-Dist: nbformat ; extra == 'nb'
Requires-Dist: ipython ; extra == 'nb'
Requires-Dist: ipykernel ; extra == 'nb'

# Ecallisto NG 
Ecallisto NG is a compact yet effective Python package designed to facilitate seamless interaction with the Ecallisto API (Rest API built with FastAPI). It provides a simple interface to fetch data from the API, as well as some basic data processing and plotting capabilities. Behind the Rest API, there is a TimeScaleDB database, which is a time-series database. Thus, data access by time, with aggregation functions, is fast and possible.

## Background
The package is constructed in Python 3.9 and utilizes the `requests` library to directly access the Ecallisto Rest API via the link: [https://v000792.fhnw.ch/api/redoc](https://v000792.fhnw.ch/api/redoc).
Currently, not all data is added to the database. Feel free to reach out if you need data before 2020. 

## Installation
To install this package, clone this repository and use pip for installation. Execute the following command in your terminal:
```pip install -e .```

## PyPI
Ecallisto NG is conveniently available on PyPI as well. To download, visit the following link: [https://pypi.org/project/ecallisto-ng/](https://pypi.org/project/ecallisto-ng/)

## Example
Please have a look at the jupyter notebook under `example`. 

## Usage
Here's a guide on how to use the different features of Ecallisto NG. Be aware that data is cached automatically in your working directory under `ecallisto_ng_cache`. Feel free to delete this folder if you want to fetch the data again.

### Data Fetching
Fetching data is easy using the `get_data` function, housed under the `ecallisto_ng.data_fetching.get_data` module. Here's an example:

```python
from ecallisto_ng.data_fetching.get_data import get_data

parameters = {
    "instrument_name": "austria_unigraz_01",
    "start_datetime": "2021-03-01 06:30:00",
    "end_datetime": "2021-03-07 23:30:00",
    "timebucket": "15m",
    "agg_function": "MAX",
}

df = get_data(**parameters)
```

### Getting Data Availability
You can also check the availability of data using the `get_tables` and `get_table_names_with_data_between_dates` function, housed under the `ecallisto_ng.data_fetching.get_information` module. Here's an example:

```python
from ecallisto_ng.data_fetching.get_information import get_tables, get_table_names_with_data_between_dates
from datetime import datetime, timedelta

get_tables()[:5]

get_table_names_with_data_between_dates(
    start_datetime=(datetime.now() - timedelta(hours=24)).strftime("%Y-%m-%d %H:%M:%S"),
    end_datetime=datetime.now().strftime("%Y-%m-%d %H:%M:%S")
)
```

### Plotting 
Ecallisto NG provides basic plotting capabilities. Here's an example of how to generate a spectogram:
```python
from ecallisto_ng.plotting.utils import fill_missing_timesteps_with_nan, plot_spectogram

df_filled = fill_missing_timesteps_with_nan(df)
plot_spectogram(df_filled,  parameters["instrument_name"], parameters["start_datetime"], parameters["end_datetime"])
```

### Spectogram editing
We also provide some basic functionalities to edit the spectogram. Here's how you can do it:
```python
from ecallisto_ng.data_processing.utils import elimwrongchannels, subtract_constant_background, subtract_rolling_background

df = elimwrongchannels(df)
df = fill_missing_timesteps_with_nan(df)
df = subtract_constant_background(df)
df = subtract_rolling_background(df)

plot_spectogram(df,  parameters["instrument_name"], parameters["start_datetime"], parameters["end_datetime"])
```
These simple commands allow you to easily manipulate spectogram data, enabling effective use of the Ecallisto API for your needs.
