Quick Start Guide for NSDLib

NSDlib (Network source detection library) is a comprehensive library designed for detecting sources of propagation in networks. This library offers a variety of algorithms that help researchers and developers analyze and identify the origins of information (epidemic etc.) spread within networks.

Installation

Install NSDLib using pip:

pip install nsdlib

Basic Usage

NSDLib offers two approaches for computing centrality measures: direct function calls and using the compute_centrality method with centrality enums.

‘SourceDetector’ class

by utilizing ‘SourceDetector’ class and configuring it with ‘SourceDetectionConfig’ object. This approach allows for seamless source detection and result evaluation.

import networkx as nx

from nsdlib.common.models import SourceDetectionConfig
from nsdlib.source_detection import SourceDetector
from nsdlib.taxonomies import NodeEvaluationAlgorithm


G = nx.karate_club_graph()

config = SourceDetectionConfig(
    node_evaluation_algorithm=NodeEvaluationAlgorithm.NETSLEUTH,
)

source_detector = SourceDetector(config)

result, evaluation = source_detector.detect_sources_and_evaluate(G=G,
                                        IG=G, real_sources=[0,33])
print(evaluation)

Direct method calls

by importing and using specific method, each method has appropriate prefix to understand what is the purpose of it:

import networkx as nx

import nsdlib as nsd

G = nx.karate_club_graph()
IG = G.copy()
IG.remove_nodes_from([10,15,20,33])
real_sources = [0,8]

EIG = nsd.reconstruction_sbrp(G, IG)

outbreaks = nsd.outbreaks_leiden(EIG)

detected_sources = []
for outbreak in outbreaks.communities:
    outbreak_G = G.subgraph(outbreak)
    nodes_evaluation = nsd.evaluation_jordan_center(outbreak_G)
    outbreak_detected_source = max(nodes_evaluation, key=nodes_evaluation.get)
    print(f"Outbreak: {outbreak}, Detected Source: {outbreak_detected_source}")
    detected_sources.append(outbreak_detected_source)

evaluation = nsd.compute_source_detection_evaluation(
    G=EIG,
    real_sources=real_sources,
    detected_sources=detected_sources,
)
print(evaluation)

This method allows you to directly specify the process of source detection, making it easy to do any modifications to standardlogic.

Enum usage

by using appropriate enum and method for computing desired method:

import networkx as nx

import nsdlib as nsd
from nsdlib import PropagationReconstructionAlgorithm, NodeEvaluationAlgorithm, OutbreaksDetectionAlgorithm

G = nx.karate_club_graph()
IG = G.copy()
IG.remove_nodes_from([10,15,20,33])
real_sources = [0,8]

EIG = nsd.reconstruct_propagation(G, IG, PropagationReconstructionAlgorithm.SBRP)

outbreaks = nsd.identify_outbreaks(EIG, OutbreaksDetectionAlgorithm.LEIDEN)
outbreaks_G = nsd.create_subgraphs_based_on_outbreaks(EIG, outbreaks)
detected_sources = []
for outbreak in outbreaks_G:
    nodes_evaluation = nsd.evaluate_nodes(outbreak, NodeEvaluationAlgorithm.CENTRALITY_AVERAGE_DISTANCE)
    outbreak_detected_source = max(nodes_evaluation, key=nodes_evaluation.get)
    print(f"Outbreak: {outbreak}, Detected Source: {outbreak_detected_source}")
    detected_sources.append(outbreak_detected_source)

evaluation = nsd.compute_source_detection_evaluation(
    G=EIG,
    real_sources=real_sources,
    detected_sources=detected_sources,
)
print(evaluation)

This approach is more flexible and allows for the computation of multiple techniques at once or when iterating over multiple methods making it easy to perform analysis of selected set of techniques.

If you would like to test NSDLib functionalities without installing it on your machine consider using the preconfigured Jupyter notebook.