Awesome

Description

This repository contains a collection of containerized (dockerized) time series anomaly detection methods that can easily be evaluated using TimeEval. Some of the algorithm's source code is access restricted and we just provide the TimeEval stubs and manifests. We are happy to share our TimeEval adaptations of excluded algorithms upon request, if the original authors approve this.

Each folder contains the implementation of an algorithm that is built into a runnable Docker container using GitHub Actions. We host the algorithm Docker images on GitHub. Thus, the namespace prefix (repository) for the Docker images is ghcr.io/timeeval/.

Overview

Usage

Use the published algorithm images

Please always use a version-tagged Docker image for your algorithms to ensure reproducibility!

You can pull the TimeEval algorithm images directly from the GitHub registry. This registry does not require authentication.

docker pull ghcr.io/timeeval/<algorithm_name>:0.3.0

Build the algorithm images

Each algorithm in this repository is bundled in a self-contained Docker image so that it can be executed with a single command and no additional dependencies must be installed. This allows you to test the algorithm without installing its dependencies on your machine. The only requirement is a (x86-)Docker runtime.

In the following, we assume that you want to build the Docker image for the lof-algorithm.

:warning: Use correct version tags!

Please tag the base and intermediate images with the correct version. You can find the required version for each algorithm image in its Dockerfile. E.g. for lof the version for pyod must be 0.3.0 (as of 2023-12-16):

FROM ghcr.io/timeeval/pyod:0.3.0

Prerequisites

You need the following tools installed on your development machine:

• git
• docker
• access to this repository
• (optionally) Docker BuildKit

Please make yourself familiar with the concepts of TimeEval, and read the TimeEval documentation and this document carefully!

1. Prepare base image

You'll need the required base Docker images to build your algorithm's image. You can either pull the base image from the registry or build it yourself. In this guide, we assume that you want to build all Docker images locally.

1. Clone this repository and change to its root folder

   git clone https://github.com/TimeEval/TimeEval-algorithms.git
   cd TimeEval-algorithms
   

2. Change to the 0-base-images folder:

   cd 0-base-images
   

3. Build your desired base image:

   docker build -t ghcr.io/timeeval/python3-base:0.3.0 python3-base
   

Prepare intermediate image (optional)

Because the algorithm lof depends on an intermediate image, we, first, need to build the required intermediate image pyod. Please see the table in this repository's README for the dependencies.

You can build the intermediate image pyod using these commands:

cd ../1-intermediate-images
docker build -t ghcr.io/timeeval/pyod:0.2.5 pyod

Build algorithm image

Once you have built all dependent images, you can build your algorithm image from the base image(s):

1. Change to the repository's root directory:

   cd ..
   

2. Build the Docker image for your algorithm (lof in this case):

   docker build -t ghcr.io/timeeval/lof:0.3.0 ./lof
   

Testing an algorithm and its TimeEval integration

Testing an algorithm locally can be done in two different ways:

1. Test the algorithm's code directly (using the tools provided by the programming language)
2. Test the algorithm within its docker container

The first option is specific to the programming language, so we won't cover it here.

Each algorithm in this repository will be bundled in a self-contained Docker image so that it can be executed with a single command and no additional dependencies must be installed. This allows you to test the algorithm without installing its dependencies on your machine. The only requirement is a (x86-)Docker runtime. Follow the below steps to test your algorithm using Docker (examples assume that you want to build the image for the LOF algorithm):

1. Pull or build the algorithm image We refer the reader to the previous section for detailed instructions.

2. Train your algorithm (optional) If your algorithm is supervised or semi-supervised, execute the following command to perform the training step (not necessary for LOF):

   mkdir -p results
   docker run --rm \
       -v $(pwd)/data:/data:ro \
       -v $(pwd)/results:/results:rw \
   #    -e LOCAL_UID=<current user id> \
   #    -e LOCAL_GID=<current groupid> \
     ghcr.io/timeeval/<your_algorithm>:latest execute-algorithm '{
       "executionType": "train",
       "dataInput": "/data/dataset.csv",
       "dataOutput": "/results/anomaly_scores.ts",
       "modelInput": "/results/model.pkl",
       "modelOutput": "/results/model.pkl",
       "customParameters": {}
     }'
   

   Be warned that the result and model files will be written to the results-directory as the root-user if you do not pass the optional environment variables LOCAL_UID and LOCAL_GID to the container.

3. Execute your algorithm Run the following command to perform the execution step of your algorithm:

   mkdir -p results
   TIMEEVAL_ALGORITHM=lof
   docker run --rm \
       -v $(pwd)/data:/data:ro \
       -v $(pwd)/results:/results:rw \
   #    -e LOCAL_UID=<current user id> \
   #    -e LOCAL_GID=<current groupid> \
     ghcr.io/timeeval/${TIMEEVAL_ALGORITHM}:latest execute-algorithm '{
       "executionType": "execute",
       "dataInput": "/data/dataset.csv",
       "dataOutput": "/results/anomaly_scores.ts",
       "modelInput": "/results/model.pkl",
       "modelOutput": "/results/model.pkl",
       "customParameters": {}
     }'
   

   Be warned that the result and model files will be written to the results-directory as the root-user if you do not pass the optional environment variables LOCAL_UID and LOCAL_GID to the container.