Visibility Graphs

class driada.recurrence.visibility.VisibilityGraph(data, method='horizontal', directed=False, create_nx_graph=False)[source]

Bases: Network

Visibility graph from 1D time series.

Two time points are connected if no intermediate value blocks the line of sight between them (NVG), or if all intermediate values are below both endpoints (HVG).

Parameters:

data (array-like, 1D) – Raw time series values.
method ({'horizontal', 'natural'}, default='horizontal') – ‘horizontal’ (HVG): O(N) via monotone stack. Default. ‘natural’ (NVG): O(N^2) pairwise line-of-sight. Slow for N > ~2000.
directed (bool, default=False) – If True, edges point forward in time only.

__init__(data, method='horizontal', directed=False, create_nx_graph=False)[source]

Initialize a Network object from adjacency matrix or NetworkX graph.

Creates a network representation with automatic detection of directed/weighted properties if not specified. Supports preprocessing to extract connected components.

Parameters:

adj (scipy.sparse matrix or None) – Adjacency matrix. Mutually exclusive with graph parameter.
graph (networkx.Graph/DiGraph or None) – NetworkX graph object. Mutually exclusive with adj parameter.
preprocessing (str or None, default="giant_cc") –
Preprocessing method:
- None: No preprocessing
- ”remove_isolates”: Remove isolated nodes
- ”giant_cc”: Extract giant connected component
- ”giant_scc”: Extract giant strongly connected component (directed only)
name (str, default="") – Name identifier for the network.
pos (dict or None) – Node positions as {node: (x, y)} dictionary.
verbose (bool, default=False) – Whether to print progress messages.
create_nx_graph (bool, default=True) – Whether to create NetworkX graph from adjacency matrix.
node_attrs (dict or None) – Node attributes as {node: {attr: value}} nested dictionary.
logger (logging.Logger or None) – Logger instance for logging messages.
**network_args –
Additional network parameters:
- directed : bool or None (auto-detected if None)
- weighted : bool or None (auto-detected if None)
- real_world : bool (affects directionality validation)

adj

Adjacency matrix in sparse format.

Type:: scipy.sparse matrix

graph

NetworkX graph representation.

Type:: networkx.Graph/DiGraph or None

directed

Whether the network is directed.

Type:: bool

weighted

Whether the network has weighted edges.

Type:: bool

n

Number of nodes.

Type:: int

outdeg

Out-degree sequence (set by get_node_degrees()).

Type:: np.ndarray

indeg

In-degree sequence (set by get_node_degrees()).

Type:: np.ndarray

init_method

Initialization method used (‘adj’ or ‘graph’).

Type:: str

_calculated_directionality

Fraction of asymmetric edges (0.0 to 1.0).

Type:: float

network_params

Original network parameters passed to constructor.

Type:: dict

real_world

Whether this is a real-world network.

Type:: bool

_init_to_final_node_mapping

Mapping from initial to final node indices after preprocessing.

Type:: dict

lem_emb

Placeholder for Laplacian eigenmaps embedding.

Type:: None

trans, lap, nlap, rwlap, lap_out, lap_in

Various matrix representations (initialized to None).

Type:: None or array

n_cc

Number of connected components (set during some preprocessing).

Type:: int or None

n_scc

Number of strongly connected components (set during some preprocessing).

Type:: int or None

Raises:: ValueError – If both adj and graph are provided or neither is provided.

Notes

The constructor automatically computes node degrees after initialization. For large sparse matrices, auto-detection of directed/weighted properties uses efficient sparse operations to avoid memory issues.

property timeseries_data: Original time series data.

property vg_method: Construction method (‘horizontal’ or ‘natural’).