diff --git a/.github/workflows/linux_installation.yaml b/.github/workflows/linux_installation.yaml new file mode 100644 index 00000000..aa5d4138 --- /dev/null +++ b/.github/workflows/linux_installation.yaml @@ -0,0 +1,23 @@ +name: Package Installation + +on: [push, pull_request] + +jobs: + linux-installation: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + + - name: Install dependencies + run: pip install poetry + + - name: Run installation script + run: | + chmod +x scripts/install_user_linux.sh && ./scripts/install_user_linux.sh + + - name: Run example + run: poetry run python example.py diff --git a/.github/workflows/windows_installation.yaml b/.github/workflows/windows_installation.yaml new file mode 100644 index 00000000..5da7128e --- /dev/null +++ b/.github/workflows/windows_installation.yaml @@ -0,0 +1,24 @@ +name: Package Installation + +on: [push, pull_request] + +jobs: + windows-installation: + + runs-on: windows-latest + + steps: + - uses: actions/checkout@v4 + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + + - name: Install dependencies + run: pip install poetry + + - name: Run installation script + run: | + ./scripts/install_user_windows.ps1 + poetry add pyqt5-qt5==5.15.2 + + - name: Run example + run: poetry run python example.py diff --git a/README.md b/README.md index 7e22b7cc..c7bf4457 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# PySATL-CPD +PySATL-CPD [status-shield]: https://img.shields.io/github/actions/workflow/status/PySATL/pysatl-cpd/.github/workflows/check.yaml?branch=main&event=push&style=for-the-badge&label=Checks [status-url]: https://github.com/PySATL/pysatl-cpd/blob/main/.github/workflows/check.yaml @@ -28,30 +28,44 @@ At the moment, the module implements the following CPD algorithms: ## Requirements - Python 3.10+ + - Poetry 2.1.0+ + + ## Installation -Clone the repository: +Clone repository: -```bash -git clone https://github.com/PySATL/pysatl-cpd +```sh +git clone https://github.com/PySATL/pysatl-cpd.git ``` -Install dependencies: + + +### Linux + +Go to repository directory and run installation script: ```bash -poetry install +cd pysatl-cpd +chmod +x scripts/install_user_linux.sh && ./scripts/install_user_linux.sh ``` -Or run ```create_user_venv.sh``` (for linux) -```bash -chmod +x create_user_venv.sh -./create_user_venv.sh + +### Windows + +Go to repository directory and run installation script: + +```shell +Set-Location pysatl-cpd +./scripts/install_user_windows.ps1 ``` + + ## Change point detection example: ```python @@ -165,21 +179,27 @@ Located change points: [25, 201, 396] ``` + ## Development -Install requirements +If you want to contribute, you should create development environment as follows: + +### Linux ```bash -poetry install --with dev +chmod +x scripts/install_dev_linux.sh && ./scripts/install_dev_linux.sh ``` -Or run ```create_dev_venv.sh``` (for linux) -```bash -chmod +x create_dev_venv.sh -./create_dev_venv.sh + +### Windows + +```shell +./scripts/install_dev_windows.ps1 ``` + + ## Pre-commit Install pre-commit hooks: @@ -194,6 +214,8 @@ Starting manually: poetry run pre-commit run --all-files --color always --verbose --show-diff-on-failure ``` + + ## License This project is licensed under the terms of the **MIT** license. See the [LICENSE](LICENSE) for more information. diff --git a/docs/Guide CPD Benchmark.md b/docs/Guide CPD Benchmark.md new file mode 100644 index 00000000..ee544c22 --- /dev/null +++ b/docs/Guide CPD Benchmark.md @@ -0,0 +1,142 @@ +# Guide benchmarking + +This guide is intended for those who plan to use the benchmarking of the pysatl-cpd project to analyze algorithms for finding change points. + +## Installation + +Clone repository: + +```bash +git clone https://github.com/PySATL/pysatl-cpd.git +``` + + + +### Linux + +Go to repository folder and run installation script: + +```bash +cd pysatl-cpd +chmod +x scripts/install_user_linux.sh && ./scripts/install_user_linux.sh +``` + + + +### Windows + +Go to repository folder and run installation script + +```shell +Set-Location pysatl-cpd +./scripts/install_user_windows.ps1 +``` + + + +## Data Generation + +### Available distributions + +| Распределение | Название | Параметры | +| ------------------- | --------------------- | ------------------------------------------------------- | +| Normal | `normal` | `mean`, `variance` | +| Exponential | `exponential` | `rate` | +| Weibull | `weibull` | `shape`, `scale` | +| Uniform | `uniform` | `min`, `max` | +| Beta | `beta` | `alpha`, `beta` | +| Gamma | `gamma` | `alpha`, `beta` | +| t-Student | `t` | `n` | +| Lognormal | `lognorm` | `s` | +| Multivariate normal | `multivariate_normal` | `mean`, in the form of string of list, z `"[0.5, 2.0]"` | + + + +### How to configure? + +To generate a test time series, create a new configuration file inside the `pysatl_cpd/examples/configs` directory. This file defines the segments that will be concatenated in order to create the final time series. + +Structure of the config file: + +```yaml +- name: config_name + distributions: + - type: dist1 + length: length1 + parameters: + parameter1_1: value1_1 + parameter1_2: value1_2 + - type: dist2 + length: length2 + parameters: + parameter2_1: value2_1 + parameter2_2: value2_2 + # ... you can add more distribution segments here +``` + +**Fields**: + +- `name`: A unique name for your configuration. +- `distributions`: A list of data segments to be generated. Each item in the list is a segment. +- `type`: The distribution type for the segment (e.g., normal, uniform). +- `length`: The length (number of data points) for this segment. +- `parameters`: The parameters required by the chosen distribution type (e.g., mean and variance for a normal distribution). + + + +> Note: The available distribution types and their parameters must match the options listed in the table above. Please refer to it for a complete list of supported distributions and their required parameters. + +### Config example + +```yaml +- name: example + distributions: + - type: exponential + length: 200 + parameters: + rate: 2.0 + - type: beta + length: 200 + parameters: + alpha: 1.0 + beta: 5.0 + - type: uniform + length: 200 + parameters: + min: 0 + max: 0.5 +``` + + + +## Algorithm configure + + + +## Experiment run + +Run example in the main directory: + +```bash +poetry run python example.py +``` + + + +## Troubleshooting + +### Import error: cannot import matplotlib + +If you saw a similar error when running the script: + +![](figures/trouble_1.png) + +And then you get this error: + +![](figures/trouble_1_1.png) + +Then try installing a lower version of the package: + +```bash +poetry add pyqt5-qt5==5.15.2 +``` diff --git a/docs/Guide CPD Benchmark.pdf b/docs/Guide CPD Benchmark.pdf new file mode 100644 index 00000000..f57923f7 Binary files /dev/null and b/docs/Guide CPD Benchmark.pdf differ diff --git a/docs/figures/trouble_1.png b/docs/figures/trouble_1.png new file mode 100644 index 00000000..5c0fb0f8 Binary files /dev/null and b/docs/figures/trouble_1.png differ diff --git a/docs/figures/trouble_1_1.png b/docs/figures/trouble_1_1.png new file mode 100644 index 00000000..f27f8cce Binary files /dev/null and b/docs/figures/trouble_1_1.png differ diff --git a/create_dev_venv.sh b/scripts/install_dev_linux.sh old mode 100755 new mode 100644 similarity index 83% rename from create_dev_venv.sh rename to scripts/install_dev_linux.sh index f3c3048c..922b5263 --- a/create_dev_venv.sh +++ b/scripts/install_dev_linux.sh @@ -1,6 +1,9 @@ #!/bin/bash +# Install dependencies +pip install poetry +# Create virtual environment if command -v python3 &>/dev/null; then PYTHON_CMD="python3" elif command -v python &>/dev/null; then @@ -18,5 +21,5 @@ echo "Using $PYTHON_CMD for installing .venv" $PYTHON_CMD -m venv .venv source .venv/bin/activate pip install poetry -poetry install --with dev +poetry install --with-dev deactivate diff --git a/scripts/install_dev_windows.ps1 b/scripts/install_dev_windows.ps1 new file mode 100644 index 00000000..fd0fe084 --- /dev/null +++ b/scripts/install_dev_windows.ps1 @@ -0,0 +1,8 @@ +pip install poetry + +py -3 -m venv .venv + +. .\.venv\Scripts\Activate.ps1 +pip install poetry +poetry install --with-dev +deactivate diff --git a/create_user_venv.sh b/scripts/install_user_linux.sh old mode 100755 new mode 100644 similarity index 87% rename from create_user_venv.sh rename to scripts/install_user_linux.sh index c0585839..ed766956 --- a/create_user_venv.sh +++ b/scripts/install_user_linux.sh @@ -1,6 +1,9 @@ #!/bin/bash +# Install dependencies +pip install poetry +# Create virtual environment if command -v python3 &>/dev/null; then PYTHON_CMD="python3" elif command -v python &>/dev/null; then diff --git a/scripts/install_user_windows.ps1 b/scripts/install_user_windows.ps1 new file mode 100644 index 00000000..1d98836c --- /dev/null +++ b/scripts/install_user_windows.ps1 @@ -0,0 +1,8 @@ +pip install poetry + +py -3 -m venv .venv + +. .\.venv\Scripts\Activate.ps1 +pip install poetry +poetry install +deactivate