[](https://fairsoftwarechecklist.net/v0.2?f=31&a=31112&i=32321&r=133)
# CEPAct
Generate complex event processing (Siddhi) activity detection apps based on IoT data and expert annotations. The general input/output and flow of the application can be seen in the following UML sequence diagram:
The application is generally structured as seen in the UML class diagram below.
## Usage
An exemplary usage of the application can be seen in the following code snippet:
```python
from cepact import (SiddhiConfig, DAGConfig, DetServiceGenerator, LocalIgnoreSensorFetcher, InfluxFetcher, GrafanaFetcher, LocalDiscretizationFetcher, AllHighLevelPatternQuery, First50HighLevelPatternQuery)
siddhi_conf = SiddhiConfig(mqtt_url = "url", mqtt_user = "usr", mqtt_pwd = "pwd", topic_prefix = "SOMEPREFIX", map_sensor_name_data_to_mqtt = {})
dag_conf = DAGConfig(
det_methods = [AllHighLevelPatternQuery(), First50HighLevelPatternQuery()],
out_dir = "out",
sampling_freq = 1,
siddhi_config = siddhi_conf,
signature_fetcher = InfluxFetcher(url = "url", auth = "authkey", org = "org", influx_station_bucket_map = {}),
annotation_param_fetcher = GrafanaFetcher(url = "url", auth = "authkey"),
ignore_sensor_fetcher = LocalIgnoreSensorFetcher("in"),
discretization_fetcher = LocalDiscretizationFetcher("in"))
generator = DetServiceGenerator(dag_conf)
generator.run()
```
As can be seen in the usage example, the features include:
- Annotations and IoT data can be provided from **various input sources**; users can implement and provide **custom fetchers** for required inputs or use **included fetchers**.
- Generated detection services apps and supporting files are written to a user-specified **output directory** in the local file system.
- Users can customize the detection service generation using a **configuration** object.
- Selection of included **detection methods** are supported, and custom implementations can be added by implementing provided interfaces.
- The package generates output according to the provided **Siddhi configuration**, ensuring compatibility with downstream systems.
There are potentially multiple concrete instantiations of the abstract data fetchers, meaning that the input of IoT data and annotations can be done in different ways. For the local input fetchers, please refer to the exemplary files in `tests/local_input_mocks/.../in`, as well as the documentation accompanying the fetcher implementations.
For the input of annotations from Grafana and the data coming from InfluxDB, we provide some guidelines for the annotations below.
## Contributing
Contributions are welcome. Both PRs from forks and issues in this repository are appreciated.
Possible (non-exhaustive list) contributions include:
- Adding new data fetchers for different data sources
- Adding new detection methods
- Improving the existing codebase
- Adding new tests
- Improving the documentation
- Adding new features (e.g. support for more complex patterns, multiple signatures per activity, etc.)
- Adding new output writers besides Siddhi (for other CEP platforms)
For more information on contributing, please refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
## Grafana Annotation Guidelines
Generates CEP apps and signatures based on Grafana annotations.
Annotation rules:
- Name of _start_ annotation `START_Activity-Name-Here`
- Note, that the activity name must match the activity name in the Camunda log for evaluation
- Analogous for `END_`
- First tag must be some unique key
- Second tag must be `activity`
- Third tag must be _station_ code, e.g. `OV_1`, `HYGIENE_STATION`
- For detection apps spanning multiple components/stations/resources, this tag needs to include all of them separated by a hyphen, e.g. `HYGIENE_STATION-LEFT_DONATION`
- Fourth tag and all others behind can be used to _ignore_ certain _sensors_ in the activity signature and for the creation
of the CEP Siddhi apps (can be either at START or END annotation):
- add `ignore-SENSORNAME` to the tag to ignore the sensor for only this activity-signature/-app, e.g. `ignore-light_l5`
- if you want to ignore a certain sensor in general, i.e. for all activities, and don't want to repeat the tag, just
tag it with `ignoregen-SENSORENAME`, e.g. `ignoregen-movepos_x`
## InfluxDB Guidelines
The IoT time series data to extract the activity signature from can be stored on InfluxDB. The data should be stored in a bucket with and the naming
should be specified in the `influx_station_bucket_map` in the `DAGConfig`.
# History
Add new entries to the top of the list.
## 2024-02-12, v0.1.0
- First release of the `cepact` package.
Raw data
{
"_id": null,
"home_page": "https://github.com/ics-unisg/activity-detection-services-generator",
"name": "cepact",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "activity detection, iot, pattern recognition, domain experts, smart factory",
"author": "\"ICS, University of St.Gallen\"",
"author_email": "\"aaron.kurz@unisg.ch\"",
"download_url": "https://files.pythonhosted.org/packages/5f/0d/bb8de6e7593fe805ccb73e08a355e5b25c6cedfe651db07754947109b827/cepact-0.1.0.tar.gz",
"platform": null,
"description": "[](https://fairsoftwarechecklist.net/v0.2?f=31&a=31112&i=32321&r=133)\n\n# CEPAct\n\nGenerate complex event processing (Siddhi) activity detection apps based on IoT data and expert annotations. The general input/output and flow of the application can be seen in the following UML sequence diagram:\n\n\n\nThe application is generally structured as seen in the UML class diagram below.\n\n\n\n## Usage\n\nAn exemplary usage of the application can be seen in the following code snippet:\n\n```python\nfrom cepact import (SiddhiConfig, DAGConfig, DetServiceGenerator, LocalIgnoreSensorFetcher, InfluxFetcher, GrafanaFetcher, LocalDiscretizationFetcher, AllHighLevelPatternQuery, First50HighLevelPatternQuery)\n\nsiddhi_conf = SiddhiConfig(mqtt_url = \"url\", mqtt_user = \"usr\", mqtt_pwd = \"pwd\", topic_prefix = \"SOMEPREFIX\", map_sensor_name_data_to_mqtt = {})\n\ndag_conf = DAGConfig(\n det_methods = [AllHighLevelPatternQuery(), First50HighLevelPatternQuery()],\n out_dir = \"out\",\n sampling_freq = 1,\n siddhi_config = siddhi_conf,\n signature_fetcher = InfluxFetcher(url = \"url\", auth = \"authkey\", org = \"org\", influx_station_bucket_map = {}),\n annotation_param_fetcher = GrafanaFetcher(url = \"url\", auth = \"authkey\"),\n ignore_sensor_fetcher = LocalIgnoreSensorFetcher(\"in\"),\n discretization_fetcher = LocalDiscretizationFetcher(\"in\"))\n\ngenerator = DetServiceGenerator(dag_conf)\ngenerator.run()\n```\nAs can be seen in the usage example, the features include:\n- Annotations and IoT data can be provided from **various input sources**; users can implement and provide **custom fetchers** for required inputs or use **included fetchers**.\n- Generated detection services apps and supporting files are written to a user-specified **output directory** in the local file system.\n- Users can customize the detection service generation using a **configuration** object.\n- Selection of included **detection methods** are supported, and custom implementations can be added by implementing provided interfaces.\n- The package generates output according to the provided **Siddhi configuration**, ensuring compatibility with downstream systems.\n\nThere are potentially multiple concrete instantiations of the abstract data fetchers, meaning that the input of IoT data and annotations can be done in different ways. For the local input fetchers, please refer to the exemplary files in `tests/local_input_mocks/.../in`, as well as the documentation accompanying the fetcher implementations.\n\nFor the input of annotations from Grafana and the data coming from InfluxDB, we provide some guidelines for the annotations below.\n\n## Contributing\nContributions are welcome. Both PRs from forks and issues in this repository are appreciated.\nPossible (non-exhaustive list) contributions include:\n- Adding new data fetchers for different data sources\n- Adding new detection methods\n- Improving the existing codebase\n- Adding new tests\n- Improving the documentation\n- Adding new features (e.g. support for more complex patterns, multiple signatures per activity, etc.)\n- Adding new output writers besides Siddhi (for other CEP platforms)\n\nFor more information on contributing, please refer to the [CONTRIBUTING.md](./CONTRIBUTING.md) file.\n\n## Grafana Annotation Guidelines\nGenerates CEP apps and signatures based on Grafana annotations.\nAnnotation rules:\n- Name of _start_ annotation `START_Activity-Name-Here`\n - Note, that the activity name must match the activity name in the Camunda log for evaluation\n- Analogous for `END_`\n- First tag must be some unique key\n- Second tag must be `activity`\n- Third tag must be _station_ code, e.g. `OV_1`, `HYGIENE_STATION`\n - For detection apps spanning multiple components/stations/resources, this tag needs to include all of them separated by a hyphen, e.g. `HYGIENE_STATION-LEFT_DONATION`\n- Fourth tag and all others behind can be used to _ignore_ certain _sensors_ in the activity signature and for the creation\nof the CEP Siddhi apps (can be either at START or END annotation):\n - add `ignore-SENSORNAME` to the tag to ignore the sensor for only this activity-signature/-app, e.g. `ignore-light_l5`\n - if you want to ignore a certain sensor in general, i.e. for all activities, and don't want to repeat the tag, just \n tag it with `ignoregen-SENSORENAME`, e.g. `ignoregen-movepos_x`\n\n## InfluxDB Guidelines\nThe IoT time series data to extract the activity signature from can be stored on InfluxDB. The data should be stored in a bucket with and the naming \nshould be specified in the `influx_station_bucket_map` in the `DAGConfig`.\n\n# History\n\nAdd new entries to the top of the list.\n\n## 2024-02-12, v0.1.0\n- First release of the `cepact` package.\n",
"bugtrack_url": null,
"license": "GNU Affero General Public License v3 (AGPLv3)",
"summary": "Create CEP activity detection services from expert annotations and IoT data.",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/ics-unisg/activity-detection-services-generator/issues",
"Homepage": "https://github.com/ics-unisg/activity-detection-services-generator"
},
"split_keywords": [
"activity detection",
" iot",
" pattern recognition",
" domain experts",
" smart factory"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d1c77db29a3236daa735eb9296ab968c83d8de1832d90a793b76c0a6d8dc90e3",
"md5": "173a6bd5252c6a6a3af154bd2ba2d89d",
"sha256": "11af39caf82683e299720ea369243aab726228e8fdf8113ec14cd5d0b094f71a"
},
"downloads": -1,
"filename": "cepact-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "173a6bd5252c6a6a3af154bd2ba2d89d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 48730,
"upload_time": "2025-02-12T11:05:50",
"upload_time_iso_8601": "2025-02-12T11:05:50.248379Z",
"url": "https://files.pythonhosted.org/packages/d1/c7/7db29a3236daa735eb9296ab968c83d8de1832d90a793b76c0a6d8dc90e3/cepact-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5f0dbb8de6e7593fe805ccb73e08a355e5b25c6cedfe651db07754947109b827",
"md5": "c0e53824183288b4a9be67187602d7c5",
"sha256": "4d035eb6f4f389b0876312925480f4d537cbbfcf6245e9d74b9d5fada1d66a5f"
},
"downloads": -1,
"filename": "cepact-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c0e53824183288b4a9be67187602d7c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 40335,
"upload_time": "2025-02-12T11:05:53",
"upload_time_iso_8601": "2025-02-12T11:05:53.721395Z",
"url": "https://files.pythonhosted.org/packages/5f/0d/bb8de6e7593fe805ccb73e08a355e5b25c6cedfe651db07754947109b827/cepact-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-12 11:05:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ics-unisg",
"github_project": "activity-detection-services-generator",
"github_not_found": true,
"lcname": "cepact"
}
JSON
