Skip to content

Graph Models API

AnoEdgeL, ISCONNA, and MIDAS consume one dynamic edge at a time. SignedGraphSketchDetector additionally tracks which graph hosts that edge.

AnoEdgeL

Python
AnoEdgeL(source_key: str = 'src', destination_key: str = 'dst', time_key: str | None = 't', count_min_rows: int = 256, count_min_cols: int = 256, num_hashes: int = 4, num_dense_submatrices: int = 1, time_decay_factor: float = 1.0, warm_up_samples: int = 0, normalize_score: bool = False, predict_threshold: float = 0.5, seed: int | None = None)

Bases: BaseModel

AnoEdge-L local dense-submatrix detector for dynamic graph edge streams.

Source and destination identifiers are hashed into higher-order count-min sketch matrices. For every sketch plane, one or more local dense submatrices are maintained with the authors' greedy add/delete updates. The edge score is the minimum across planes of the summed local-submatrix likelihoods.

The authors' implementation inserts an edge before updating submatrices and scoring it. score_one reproduces that candidate-inclusive operation on copies of the small submatrix states, without mutating the sketch or advancing time. learn_one applies the same operation to learned state.

Notes: - Source and destination identifiers must be integer-like numbers. - Scores are continuous and non-negative; denser anomalous edges score higher. - With normalize_score=True, scores are squashed to [0, 1). - State is bounded by the configured higher-order sketch dimensions.

Parameters:

Name Type Description Default
source_key str

Input field containing the integer-like source identifier.

 'src'
destination_key str

Input field containing the integer-like destination identifier.

 'dst'
time_key str | None

Input field containing a non-decreasing integer-like time bucket. None assigns a new one-based bucket to every learned arrival.

 't'
count_min_rows int

Row dimension of every higher-order sketch plane.

 256
count_min_cols int

Column dimension of every higher-order sketch plane.

 256
num_hashes int

Number of independently hashed sketch planes.

 4
num_dense_submatrices int

Local dense submatrices maintained per plane. It cannot exceed either sketch dimension.

 1
time_decay_factor float

Factor in (0, 1] applied to sketches and local submatrices when the time bucket advances.

 1.0
warm_up_samples int

Number of learned edges before scoring begins.

 0
normalize_score bool

Apply score / (1 + score) to the non-negative raw score.

 False
predict_threshold float

Boundary used by predict_one on the selected raw or normalized score scale.

 0.5
seed int | None

Seed for model-local sketch hash generation.

 None
References

Bhatia, S., Wadhwa, M., Kawaguchi, K., Shah, N., Yu, P. S., & Hooi, B. (2023). Sketch-Based Anomaly Detection in Streaming Graphs. https://doi.org/10.1145/3580305.3599273 Original implementation: https://github.com/Stream-AD/AnoGraph

n_samples_seen property

Python
n_samples_seen: int

Number of observed samples processed via learn_one.

reset

Python
reset() -> None

Reset learned state while keeping hyperparameters.

learn_one

Python
learn_one(x: dict[str, float]) -> None

Insert an edge and update the local dense-submatrix states.

score_one

Python
score_one(x: dict[str, float]) -> float

Preview the candidate-inclusive AnoEdge-L score without mutation.

predict_one

Python
predict_one(x: dict[str, float]) -> int

Return binary anomaly prediction using predict_threshold.

ISCONNA

Python
ISCONNA(source_key: str = 'src', destination_key: str = 'dst', time_key: str | None = 't', count_min_rows: int = 2, count_min_cols: int = 3000, time_decay_factor: float = 0.7, alpha: float = 1.0, beta: float = 1.0, gamma: float = 0.5, include_endpoints: bool = True, warm_up_samples: int = 0, normalize_score: bool = False, seed: int | None = None)

Bases: BaseModel

ISCONNA frequency-and-pattern detector for dynamic graph edge streams.

This implementation follows the authors' ACore, EdgeOnlyCore, and EdgeNodeCore implementations. Each sketch tracks three signals:

  • frequency within the current timestamp against accumulated frequency,
  • width of consecutive timestamps in which an edge or node is present,
  • gap length of consecutive timestamps in which it is absent.

Their G-test scores are combined as frequency**alpha * width**beta * gap**gamma. With include_endpoints=True, the maximum edge/source/destination score is used for each component, matching EdgeNodeCore.

score_one previews the candidate-inclusive author update without mutating state. Calling score_one(x) followed by learn_one(x) therefore produces the same score as the authors' combined update-and-score call while preserving the library's score-before-learn convention.

Notes: - Source and destination identifiers must be integer-like numbers. - Scores are continuous and non-negative. - With normalize_score=True, scores are squashed to [0, 1). - State is bounded by a fixed sketch size.

Parameters:

Name Type Description Default
source_key str

Input field containing the integer-like source identifier.

 'src'
destination_key str

Input field containing the integer-like destination identifier.

 'dst'
time_key str | None

Input field containing a non-decreasing integer-like time bucket. None assigns a new one-based bucket to every learned arrival.

 't'
count_min_rows int

Number of independently hashed rows in each sketch.

 2
count_min_cols int

Number of counters per sketch row.

 3000
time_decay_factor float

Factor in (0, 1] applied to current pattern counts during bucket transitions.

 0.7
alpha float

Non-negative exponent of the frequency G-test component.

 1.0
beta float

Non-negative exponent of the consecutive-width G-test component.

 1.0
gamma float

Non-negative exponent of the absence-gap G-test component.

 0.5
include_endpoints bool

Combine edge, source, and destination components by component-wise maxima. False scores only edge patterns.

 True
warm_up_samples int

Number of learned edges before scoring begins.

 0
normalize_score bool

Apply score / (1 + score) to the non-negative raw combined statistic.

 False
seed int | None

Seed for model-local sketch hash generation.

 None
References

Liu, R., Bhatia, S., & Hooi, B. (2021). Isconna: Streaming Anomaly Detection with Frequency and Patterns. https://arxiv.org/abs/2104.01632 Original implementation: https://github.com/liurui39660/Isconna

n_samples_seen property

Python
n_samples_seen: int

Number of observed samples processed via learn_one.

reset

Python
reset() -> None

Reset learned state while keeping hyperparameters.

learn_one

Python
learn_one(x: dict[str, float]) -> None

Update detector state with one sample.

score_one

Python
score_one(x: dict[str, float]) -> float

Compute the candidate-inclusive anomaly score without mutating state.

MIDAS

Python
MIDAS(source_key: str = 'src', destination_key: str = 'dst', time_key: str | None = 't', count_min_rows: int = 2, count_min_cols: int = 1024, time_decay_factor: float = 0.5, warm_up_samples: int = 0, use_relational: bool = True, normalize_score: bool = False, seed: int | None = None)

Bases: BaseModel

MIDAS or MIDAS-R detector for dynamic edge streams.

use_relational=False follows the authors' NormalCore: the current edge sketch is cleared at each new timestamp and the candidate-inclusive edge count is scored against its cumulative count.

use_relational=True follows RelationalCore (MIDAS-R): current edge, source, and destination sketches are decayed at each new timestamp, and the final score is the maximum of their three published chi-square scores.

score_one previews rollover and candidate insertion without mutating state. Calling score_one(x) followed by learn_one(x) therefore matches the authors' combined update-and-score operation under this library's score-before-learn convention.

Notes: - Source and destination identifiers must be integer-like numbers. - Scores are continuous and non-negative. - With normalize_score=True, scores are squashed to [0, 1). - State is bounded by fixed-size sketches.

Parameters:

Name Type Description Default
source_key str

Input field containing the integer-like source identifier.

 'src'
destination_key str

Input field containing the integer-like destination identifier.

 'dst'
time_key str | None

Input field containing a non-decreasing integer-like time bucket. None assigns a new one-based bucket to every learned arrival.

 't'
count_min_rows int

Number of independently hashed rows in each count-min sketch.

 2
count_min_cols int

Number of counters per sketch row.

 1024
time_decay_factor float

Factor in (0, 1] applied to current edge and endpoint sketches at bucket changes in relational mode. NormalCore clears its current edge sketch instead.

 0.5
warm_up_samples int

Number of learned edges before scoring begins.

 0
use_relational bool

Use MIDAS-R endpoint sketches and decayed current counts. False selects the edge-only NormalCore.

 True
normalize_score bool

Apply score / (1 + score) to the non-negative raw statistic.

 False
seed int | None

Seed for model-local sketch hash generation.

 None
References

Bhatia, S., Hooi, B., Yoon, M., Shin, K., & Faloutsos, C. (2020). MIDAS: Microcluster-Based Detector of Anomalies in Edge Streams. https://ojs.aaai.org/index.php/AAAI/article/view/5724 Original implementation: https://github.com/Stream-AD/MIDAS

n_samples_seen property

Python
n_samples_seen: int

Number of observed samples processed via learn_one.

reset

Python
reset() -> None

Reset learned state while keeping hyperparameters.

learn_one

Python
learn_one(x: dict[str, float]) -> None

Update detector state with one edge.

score_one

Python
score_one(x: dict[str, float]) -> float

Preview the candidate-inclusive MIDAS or MIDAS-R score.

SignedGraphSketchDetector

Python
SignedGraphSketchDetector(graph_key: str = 'graph', source_key: str = 'src', destination_key: str = 'dst', edge_type_key: str | None = None, time_key: str | None = 't', sketch_dim: int = 1024, shingle_size: int = 2, num_clusters: int = 8, max_graphs: int = 4096, warm_up_graphs: int = 32, normalize_score: bool = False, predict_threshold: float = 0.5, seed: int | None = None, eps: float = 1e-09)

Bases: BaseModel

Signed-sketch detector for graph-level structural anomalies.

The detector maintains bounded per-graph sketches over edge shingles and an online set of cluster centers over graph sketches. Incoming edges are scored by the distance between their host graph's candidate sketch and the nearest cluster center. This implementation uses signed count sketches and online Euclidean centroids; the original StreamSpot uses Hamming-distance sketches and a different clustering procedure.

Notes: - Scores are continuous and non-negative. - With normalize_score=True, scores are squashed to [0, 1). - State is bounded by max_graphs, sketch_dim, and num_clusters.

Parameters:

Name Type Description Default
graph_key str

Input field identifying the graph to which an edge belongs.

 'graph'
source_key str

Input field containing the finite numeric source identifier.

 'src'
destination_key str

Input field containing the finite numeric destination identifier.

 'dst'
edge_type_key str | None

Optional input field included in edge-shingle identity.

 None
time_key str | None

Input field containing a non-decreasing integer-like time bucket. None uses one-based arrival order.

 't'
sketch_dim int

Number of signed-count coordinates per graph sketch.

 1024
shingle_size int

Number of consecutive per-graph edge tokens in a shingle.

 2
num_clusters int

Maximum number of online Euclidean cluster centers.

 8
max_graphs int

Maximum number of active per-graph sketches. Least-recently learned graph state is evicted when the limit is exceeded.

 4096
warm_up_graphs int

Number of active graph sketches required before scoring. It cannot exceed max_graphs.

 32
normalize_score bool

Apply score / (1 + score) to the non-negative raw distance-plus-novelty score.

 False
predict_threshold float

Boundary used by predict_one on the selected raw or normalized score scale.

 0.5
seed int | None

Seed for model-local shingle hashing.

 None
eps float

Positive numerical floor in the bounded distance component.

 1e-09
References

Manzoor, E., Milajerdi, S. M., & Akoglu, L. (2016). Fast Memory-efficient Anomaly Detection in Streaming Heterogeneous Graphs. https://doi.org/10.1145/2939672.2939783 Preprint: https://arxiv.org/abs/1602.04844 Original implementation: https://github.com/sbustreamspot/sbustreamspot-core

n_samples_seen property

Python
n_samples_seen: int

Number of samples processed via learn_one.

reset

Python
reset() -> None

Reset learned state while keeping hyperparameters.

learn_one

Python
learn_one(x: dict[str, float]) -> None

Update detector state with one edge event.

score_one

Python
score_one(x: dict[str, float]) -> float

Compute anomaly score for one edge event without mutating state.

predict_one

Python
predict_one(x: dict[str, float]) -> int

Return binary anomaly prediction using predict_threshold.