AERS is a Python based wrapper for anomaly explanations modules. Modules must follow certain template (modules must inherit from base_explanation_module - see examples in modules folder). Modules can be imported into the program to perform module custom logic of anomaly explanation. This program does not address AI explainability, it rather focuses on searching patterns and relationships in data to explain anomalies. AERS wrapper (report_system.py) handles the following:
- data load: predictions, test data, labeled anomalies, channel (columns) names, normalization statistics (mean, standard deviation) all in one file of .npz format,
- modules import,
- result export in Markdown/LaTex and machine-readable JSON.
To simplify creation of .npz file, predictor.py script is provided. This script handles the following:
- model and data load (data must be .csv but can have custom column format, default format was taken from https://github.com/vorava/satellite_telemetry_generator),
- data normalization,
- predictions calculations,
- result export in .npz format, which AERS expects as input.
The program was developed and tested using Python 3.10.20, but newer versions of Python should work as fine. Dependencies are listed in requirements.txt file.
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
Listings below show usage for both scripts.
Prediction calculation module. Train data are needed for correct normalization of test data.
Full available options are:
python predictor.py [-h]
--model MODEL
--train_data TRAIN_DATA
--test_data TEST_DATA
[--out_file OUT_FILE]
[--columns COLUMNS]
where:
-h, --helpShow this help message and exit--model MODELPath to the anomaly detection model (.keras, .h5, .onnx).--train_data TRAIN_DATAPath to training telemetry data (.csv). Used for correct normalization.--test_data TEST_DATAPath to test telemetry data (.csv)--out_file OUT_FILEOutput .npz file. Serves as input for AERS.--columns COLUMNSPath to a CSV file to extract column schema from. Default columns come from satellite telemetry generator format.
Script creates inference_result.npz file which is then passed on the input of report_system.py script.
The resulting .npz file is created using function below. Users can implement their own code to create the .npz file, but .npz file must include the same elements as listed here.
def save_results(self, out_file: str):
"""
Saves the prediction results to a .npz file.
Parameters:
out_file (str): Path to the output .npz file.
The saved archive contains the following data:
- predictions: The per-channel predictions made by the model.
- test_data: The unnormalized test data used for the predictions.
- test_labels: The ground truth labels for the test data.
- feature_names: The names of the features in the test data.
- feature_means: The mean values used for normalization.
- feature_stds: The standard deviation values used for normalization.
"""
print(f"{self.print_name} Saving results...")
np.savez(
out_file,
predictions=self.predictions,
test_data=self.aligned_test_data,
test_labels=self.aligned_test_labels,
feature_names=np.array(self.feature_cols),
feature_means=self.scaler.mean_,
feature_stds=self.scaler.scale_
)
print(f"{self.print_name} Successfully saved to {out_file}")Main AERS script. Handles modules load and runs theirs codes, generates exports.
Full available options are:
python report_system.py [-h]
--results_file RESULTS_FILE
--modules MODULES [MODULES ...]
[--format {markdown,latex}]
[--out_dir OUT_DIR]
where:
-h, --helpShow this help message and exit--results_file RESULTS_FILEPath to the .npz inference results file.--modules MODULES [MODULES ...]List of paths to Python (.py) files with modules. (e.g. modules/module1.py modules/module2.py).--format {markdown,latex}Output report format (JSON is always generated).--out_dir OUT_DIRDirectory for saving reports and plots.
The image below shows whole system scheme. (1) Predictions are made by anomaly detection model and passed with other statistics and original data to AERS (2) in .npz format. AERS handles data and modules (3) load and runs modules code. In the end, outputs are generated in selected format + JSON. Modules receive data in standardized form through analyze function they inherit from base module class. Their output must be a Python dictionary with given rules (see section below). This modular architecture of whole system enables users to create their own modules and to run anomaly detection with any model or method they want.
Example run of whole pipeline with Deviation analyzation module and data generated using https://github.com/vorava/satellite_telemetry_generator.
python predictor.py \
--model models/denseae.keras \
--train_data data/train_telemetry.csv \
--test_data data/test_telemetry.csv \
--out_file results.npz
python report_system.py \
--results_file results.npz \
--modules modules/module_deviations.py \
--format markdown
This section describes how template for modules looks. Each module must inherit from class BaseExplanationModule from base_explanation_module.py. Module must implement function analyze:
def analyze(self,
test_data: pd.DataFrame,
test_labels: np.ndarray,
predictions: np.ndarray,
feature_means: np.ndarray,
feature_stds: np.ndarray,
output_dir: str) -> dict[str, Any]This function represents only interface between module and AERS. Report system provides test data in not normalized form, predictions and statistics (mean and standard deviation for each channel). Designers of modules can do whatever they want with those values, but function must return Python dictionary with structure defined below. Keys title, summary, details and plots are mandatory, additional keys and values in details are not mandatory (details and plots can be left empty: []).
Object details can contain objects of those types:
- key_value -- classic key - value pairs encapsulated in data object, with one title value
- table -- table consiting of headers, title and data
- text -- has only one key content with additional text description
Object plots stores paths to the graph objects. Based on these, graphs are visualized in the resulting Markdown/LaTeX.
{
"title": "Deviation Analysis (Feature Importance)",
"summary": summary_text,
"details": [
{
"type": "key_value",
"title": "Analysis Parameters",
"data": {
"Analyzed prediction mode": "per_channel",
"Anomaly threshold (95th percentil)": {threshold:.4f},
"Number of anomalous windows": (num_windows)
}
},
{
"type": "table",
"title": "Top Deviated Metrics",
"headers": ["Metric Name", "Average Absolute Z-Score"],
"data": table_data
},
{
"type": "text",
"content": "Some text related to the deviation module"
}
],
"plots": {
"z_score_bar_chart": plot_path
}
}To better understand what exactly function analyze takes as arguments, detailed description is written here. Keep in mind that those may vary based on how user approaches prediction step. The notes below apply when predictor.py is used:
- test data - the unnormalized test data used for the predictions in pandas DataFrame format. The data is already length-aligned with the predictions (sliding windows). The module can also extract channel names from the DataFrame columns.
- test labels - anomaly ground-truth labels (0 for normal, 1 for anomaly) for the test data, as a 1D numpy array (aligned with the time windows).
- predictions - numpy array of shape (number of time windows, number of channels) with MAE value for each time window
- feature_means - numpy 1D array with means for each channel
- feature_stds - numpy 1D arraywith standard deviations for each channel
- output_dir - directory for saving reports and plots (string).
Two modules have been created for example. See them in folder modules.
@misc{aers,
title = {Anomaly Explanation Report System},
author = {Vojtěch Orava},
date = {2026},
url = {https://github.com/vorava/aers},
}