emon-tools 0.3.0

A Python PHPFINA feeds and Api Tools to interact with EmonCms.

emon_tools

emon-tools is a Python library that provides a streamlined API interface for seamless interactions with EmonCMS, along with tools designed to analyze and visualize PhpFina files.

Explore the project Wiki for detailed documentation and guides: emon_tools Wiki.

Table of Contents

1. Installation

   • Best Practices for Installation

   • Global Installation

   • Module-Specific Installation

2. Modules

   • emon_fina

   • emon_api

3. Running Tests

4. Contributing

5. License

Installation

The emon-tools package offers flexible installation options tailored to various use cases. Depending on your requirements, you can choose to install the complete package or specific subsets of dependencies.

Best Practices for Installation

1. Environment Management: Always use a virtual environment (e.g., venv or conda) to isolate your dependencies and prevent conflicts with other projects.

2. Upgrading Dependencies: Keep your dependencies up to date by running pip install --upgrade emon-tools periodically.

3. Check Requirements: Review the module's requirements in the setup.cfg file or on the PyPI page to ensure compatibility with your system.

Global Installation

To install the entire emon-tools package along with all dependencies, run the following command:

pip install emon-tools["all"]

Included Dependencies:

• aiohttp
• numpy
• pandas
• matplotlib

Tip: This is the best option if you plan to use all features, including data manipulation and visualization.

Module-Specific Installation

You can install specific modules and their dependencies as needed. For example:

• To enable emon_fina module:

pip install emon-tools["fina"]

• To enable pandas time-series output functionality:

pip install emon-tools["fina, time_series"]

• To include graph plotting capabilities:

pip install emon-tools["fina, plot"]

• To enable emon_api module:

pip install emon-tools["api"]

• To enable emon_fina and emon_api modules:

pip install emon-tools["api, fina"]

Modules

emon_tools is modular, allowing you to install and use individual components as needed.

1. emon_fina

The emon_fina module facilitates the analysis and processing of time-series data, particularly from PhpFina file formats.

Features

• Data Reading: Efficiently read data from PhpFina file formats.
• Time-Series Analysis: Compute daily statistics such as min, max, mean, and more.
• Filtering: Validate and filter data based on custom thresholds.
• Utilities: Timestamp manipulation and interval computation tools.

Usage Example

from emon_tools.fina_time_series import FinaDataFrame
from emon_tools.emon_fina.fina_plot import PlotData
from emon_tools.emon_fina.fina_models import FinaByTimeParamsModel

fdf = FinaDataFrame(
    file_name="1",
    data_dir="/path/to/phpfina/files"
)
# Access metadata of the .meta file:
print("Meta: ", fdf.meta)

# get height days of data points from meta start_time
ts = fdf.get_df_data(
    props=FinaByTimeParamsModel(
        start_time=fr.meta.start_time,
        time_window=8 * 24 * 3600,
        time_interval=10
    )
)

PlotData.plot(data=ts)

• Wiki: See emon_fina module wiki section.

• Jupiter NoteBook: See emon_fina NoteBook

2. emon_api

The emon_api module is Emoncms python api interface, used to easy interract with an EmonCMS instance via its JSON API.

Features

• Streamlined Interface: A user-friendly Python API for EmonCMS.
• RESTful Communication: Perform seamless data exchanges with EmonCMS through JSON APIs.
• Data Management: Retrieve and manage feeds, inputs, and other EmonCMS structures with ease.

Usage Example

from emon_tools.emon_api.emon_api import EmonFeedsApi
cli = EmonApi(
    url="http://127.0.0.1:8080",
    api_key="MyAPIKey123"
)
# Get current inputs and feeds on Emoncms server
inputs = cli.list_inputs()
print("Inputs: ", inputs)
feeds = cli.list_feeds()
print("Feeds: ", feeds)

• Wiki: See emon_api module wiki section.
• Examples: Explore api_bulk_structure for input and feed supervision, as well as posting bulk dummy data.

Running Tests

To ensure everything is functioning correctly, run the test suite:

pytest -v

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with a clear description.

License

This project is licensed under the MIT License. See LICENSE for more details.