Merge branch 'release/release/1.0.1'

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,30 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behaviour**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Hardware (please complete the following information):**
+
+- OS and version: [e.g. iOS 10.7 or Windows 10]
+- Version of CEA you are using [e.g. v. 2.31.1]

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the feature you would like to have**
+Ex. I would like to have [...]
+
+**Describe the end purpose of this feature**
+Ex. So I could visualize/understand/know/apply etc..
+
+**Describe the end-user of this feature**
+Ex. A Researcher, a Student, or a Practitioner.
+
+**Provide Additional information if possible**
+EX. Screenshots, Links, Methods

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+on:
+  # should work
+  workflow_dispatch:
+  push:
+    tags:
+      - 'v*' # Push events to matching v*, i.e. v1.0, v20.15.10
+
+jobs:
+  release:
+    name: "Create Development Release"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Clone repository"
+        uses: actions/checkout@v4
+      - name: "Create Release"
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ github.ref }}
+          release_name: Release ${{ github.ref }}
+          body_path: RELEASE.md
+          draft: false
+          prerelease: false

.gitignore

@@ -109,4 +109,6 @@ GitHub.sublime-settings
 *.html
 *.csv
 *.png
-.DS_Store
+.DS_Store
+!data.csv
+!example.png

Dockerfile

@@ -15,7 +15,10 @@ ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
 
 WORKDIR /app
-
+# todo pass the csv as arcument in the cli and write documentation and add to catalog in moderate platform
+# todo static s3 report to s3 http url and dataset to download and run
+# todo dataset csv process the report data validation inide the success 200, output path as url
+# todo if faul caputure console raise exception place the htmp lo caricano gli altri su s3
 # Create a non-privileged user that the app will run under.
 # See https://docs.docker.com/go/dockerfile-user-best-practices/
 ARG UID=10001

LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+#### Copyright (c) [2024] [Roberto Chiosa]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -4,32 +4,15 @@
 define find.functions
 	@fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//'
 endef
-
-VENV := source .venv/bin/activate
-
+VENV = .venv
+PYTHON = $(VENV)/bin/python3
+PIP = $(VENV)/bin/pip
 
 help:
 	@echo 'The following commands can be used.'
 	@echo ''
 	$(call find.functions)
 
-setup: ## Setup the project
-setup:
-	python3 -m venv .venv;
-	$(VENV);
-	pip install --upgrade pip;
-	pip install .;
-	pip install -r requirements.txt;
-
-
-build: ## Build package and generate distribution archives
-build:
-	$(VENV); python3 -m build --wheel # build the package
-
-
-activate: ## Source venv and environment files for testing
-activate:
-	$(VENV);
 
 clean: ## Remove build and cache files
 clean:
@@ -47,4 +30,27 @@ docker-build:
 
 docker-run: ## Build docker image
 docker-run:
-	docker run cmp
+	docker run cmp data/data.csv Total_Power results/reports/report.html
+
+
+
+
+.PHONY: rm-git-cache
+rm-git-cache:
+	@echo "Removing git cached files"
+	git add .
+	git rm -r --cached .
+	git add .
+
+.PHONY: setup
+setup:
+	@if [ ! -d "${VENV}" ]; then \
+		echo "Creating venv"; \
+		python3 -m venv ${VENV}; \
+	fi
+	echo "Venv already exists"; \
+	source ${VENV}/bin/activate; \
+	pip install --upgrade pip; \
+	pip install poetry; \
+	poetry config virtualenvs.create false; \
+	poetry install;

README.md

@@ -1,23 +1,60 @@
-# Matrix Profile Paper
+# Contextual Matrix Profile Calculation Tool
 
 The Matrix Profile has the potential to revolutionize time series data mining because of its generality, versatility,
 simplicity and scalability. In particular it has implications for time series motif discovery, time series joins,
 shapelet discovery (classification), density estimation, semantic segmentation, visualization, rule discovery,
 clustering etc.
 
+![](./docs/example.png)
 
+**Table of Contents**
 
-![](./docs/example.png)
+* [Usage](#usage)
+    * [Data format](#data-format)
+    * [Run locally](#run-locally)
+    * [Run with Docker](#run-with-docker)
+* [Additional Information](#additional-information)
+* [Cite](#cite)
+* [Contributors](#contributors)
+* [License](#license)
+
+## Usage
+
+The tool comes with a cli that helps you to execute the script with the desired commands
+
+```console 
+$ python -m src.cmp.main -h
+
+Matrix profile
+
+positional arguments:
+  input_file     Path to file
+  variable_name  Variable name
+  output_file    Path to the output file
+
+options:
+  -h, --help     show this help message and exit
+```
+
+The arguments to pass to the script are the following:
 
-## Project Organization
+* `input_file`: The input dataset via an HTTP URL. The tool should then download the dataset from that URL; since it's a
+  presigned URL, the tool would not need to deal with authentication—it can just download the dataset directly.
+* `variable_name`: The variable name to be used for the analysis (i.e., the column of the csv that contains the
+  electrical load under analysis).
+* `output_file`: The local path to the output HTML report. The platform would then get that HTML report and upload it to
+  the object
+  storage service for the user to review later.
 
-- `src`: Folder containing the contextual matrix profile codebase (i.e., folder `cmp`) and necessary packages (i.e., `distancematrix`).
-- `tests`: Contains Python-based test cases to validate source code.
-- `pyproject.toml`: Contains metadata about the project and configurations for additional tools used to format, lint,
-  type-check, and analyze Python code. (
-  See [here](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/) for reference)
+You can run the main script through the console using either local files or download data from an external url. This
+repository comes with a sample dataset (data.csv) that you can use to generate a report and you can pass the local path
+as `input_file` argument as follows:
 
-## Getting started
+### Data format
+
+todo
+
+### Run locally
 
 Create virtual environment and activate it and install dependencies:
 
@@ -29,40 +66,51 @@ Create virtual environment and activate it and install dependencies:
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
-  pip install -r requirements.txt
+  pip install poetry
+  poetry install
   ```
 - Windows:
   ```bash
   python -m venv venv
   venv\Scripts\activate
-  pip install -r requirements.txt
+  pip install poetry
+  poetry install
   ```
 
-Run the main script through the console:
-```bash
-source .venv/bin/activate
-python -m src.cmp.main
-```
+Now you can run the script from the console by passing the desired arguments. In the following we pass the sample
+dataset [`data.csv`](src/cmp/data/data.csv) as input file and the variable `Total_Power` as the variable name to be used
+for the analysis. The output file will be saved in the [`results`](src/cmp/results) folder.
 
-You should see in the terminal a message output like the following:
+```console
+$ python -m src.cmp.main src/cmp/data/data.csv Total_Power src/cmp/results/reports/report.html
 
-```txt
+2024-08-13 12:45:42,821 [INFO](src.cmp.utils) ⬇️ Downloading file from <src/cmp/data/data.csv>
+2024-08-13 12:45:43,070 [INFO](src.cmp.utils) 📊 Data processed successfully
+
+*********************
 CONTEXT 1 : Subsequences of 05:45 h (m = 23) that start in [00:00,01:00) (ctx_from00_00_to01_00_m05_45)
 99.997%        0.0 sec
 
-- Cluster 1 (1.181 s)   -> 1 anomalies
-- Cluster 2 (0.508 s)   -> 3 anomalies
-- Cluster 3 (0.473 s)   -> 4 anomalies
-- Cluster 4 (0.658 s)   -> 5 anomalies
+- Cluster 1 (1.660 s)   -> 1 anomalies
+- Cluster 2 (0.372 s)   -> 3 anomalies
+- Cluster 3 (0.389 s)   -> 4 anomalies
+- Cluster 4 (0.593 s)   -> 5 anomalies
 - Cluster 5 (-)         -> no anomalies green
-```
 
-At the end of the execution you can find the results in the [`results`](src/cmp/results) folder.
+[...]
 
+2024-08-13 12:46:27,187 [INFO](__main__) TOTAL 0 min 44 s
+2024-08-13 12:46:32,349 [INFO](src.cmp.utils) 🎉 Report generated successfully on src/cmp/results/reports/report.html
 
-## Run using docker
+```
+
+At the end of the execution you can find the report in the path specified by the `output_file` argument, in this case
+you will find it in the [`results`](src/cmp/results) folder.
+
+### Run with Docker
 
 Build the docker image.
+
 - Makefile
   ```bash
   make docker-build
@@ -72,19 +120,21 @@ Build the docker image.
   docker build -t cmp .
   ```
 
-Run the docker image.
+Run the docker image with the same arguments as before
+
 - Makefile
   ```bash
   make docker-run
   ```
 - Linux:
   ```bash
-  docker run cmp
+  docker run cmp data/data.csv Total_Power results/reports/report.html
   ```
 
-At the end of the execution you can find the results in the [`results`](src/cmp/results) folder.
+At the end of the execution you can find the results in the [`results`](src/cmp/results) folder inside the docker
+container.
 
-### Context definition
+## Additional Information
 
 ```
 # 2) User Defined Context
@@ -124,10 +174,12 @@ contexts = GeneralStaticManager([
 
 ## Cite
 
-You can cite this work by using the following reference or either though [this Bibtex file](./docs/ref.bib).
+You can cite this work by using the following reference or either though [this Bibtex file](./docs/ref.bib) or the
+following plain text citation
 
-> Chiosa, Roberto, et al. "Towards a self-tuned data analytics-based process for an automatic context-aware detection and
-diagnosis of anomalies in building energy consumption timeseries." Energy and Buildings 270 (2022): 112302.
+> Chiosa, Roberto, et al. "Towards a self-tuned data analytics-based process for an automatic context-aware detection
+> and
+> diagnosis of anomalies in building energy consumption timeseries." Energy and Buildings 270 (2022): 112302.
 
 ## Contributors
 

RELEASE.md

@@ -0,0 +1,3 @@
+### Features:
+
+- Added command line interface for the tool