NDQL: Network Diffusion Query Language¶
NDlib
aims to an heterogeneous audience composed by technicians as well as analysts.
In order to abstract from the its programming interface we designed a query language to describe diffusion simulations, NDQL
.
Rationale¶
NDQL
is built upon the custom model definition facilities offered by NDlib
.
It provides a simple, declarative, syntax for describing and executing diffusion simulations by
- creating a custom model composed of
- node statuses;
- transition rules (expressed as combinations of
compartments
)
- creating a synthetic graph / loading an existing network
- initialize initial nodes statuses
- run the simulation
NDQL
is designed to allow those users that are not familiar to the Python language to:
- abstract the technicality of the programming interface, and
- directly describe the expected model behaviour
So far, NDQL
supports only static network analysis.
NDQL Syntax¶
An NDQL
script is composed of a minimum set of directives:
- Model definition:
- MODEL, STATUS, COMPARTMENT (+), IF-THEN-ELSE (+), RULE,
- Model initialization:
- INITIALIZE
- Network specification:
- CREATE_NETWORK ($), LOAD_NETWORK ($)
- Simulation execution:
- EXECUTE
Directives marked with (+) are optional while the ones marked with ($) are mutually exclusive w.r.t. their class.
The complete language directive specification is the following:
MODEL model_name
STATUS status_name
COMPARTMENT compartment_name
TYPE compartment_type
COMPOSE compartment_name
[PARAM param_name numeric]*
[TRIGGER status_name]
IF compartment_name_1 THEN compartment_name_2 ELSE compartment_name_3 AS rule_name
RULE rule_name
FROM status_name
TO status_name
USING compartment_name
INITIALIZE
[SET status_name ratio]+
CREATE_NETWORK network_name
TYPE network_type
[PARAM param_name numeric]*
LOAD_NETWORK network_name FROM network_file
EXECUTE model_name ON network_name FOR iterations
The CREATE_NETWORK directive can take as network_type any networkx
graph generator name (param_name are inherited from generator function parameters).
Execute/Translate NDQL files¶
NDlib
installs two command line commands:
- NDQL_translate
- NDQL_execute
The former command allows to translate a generic, well-formed, NDQL
script into an equivalent Python one. It can be executed as
NDQL_translate query_file python_file
where query_file identifies the target NDQL
script and python_file specifies the desired name for the resulting Python script.
The latter command allows to directly execute a generic, well-formed, NDQL
script.It can be executed as
NDQL_execute query_file result_file
where query_file identifies the target NDQL
script and result_file specifies the desired name for the execution results.
Execution results are saved as JSON files with the following syntax:
[{"trends":
{
"node_count": {"0": [270, 179, 15, 0, 0], "1": [30, 116, 273, 256, 239], "2": [0, 5, 12, 44, 61]},
"status_delta": {"0": [0, -91, -164, -15, 0], "1": [0, 86, 157, -17, -17], "2": [0, 5, 7, 32, 17]}
},
"Statuses": {"1": "Infected", "2": "Removed", "0": "Susceptible"}
}]
where - node_count describe the trends built on the number of nodes per status - status_delta describe the trends built on the fluctuations of number of nodes per status - Statuses provides a map from numerical id to status name
Examples¶
Here some example of models implemented using NDQL
.
SIR¶
CREATE_NETWORK g1
TYPE erdos_renyi_graph
PARAM n 300
PARAM p 0.1
MODEL SIR
STATUS Susceptible
STATUS Infected
STATUS Removed
# Compartment definitions
COMPARTMENT c1
TYPE NodeStochastic
PARAM rate 0.1
TRIGGER Infected
COMPARTMENT c2
TYPE NodeStochastic
PARAM rate 0.1
# Rule definitions
RULE
FROM Susceptible
TO Infected
USING c1
RULE
FROM Infected
TO Removed
USING c2
# Model configuration
INITIALIZE
SET Infected 0.1
EXECUTE SIR ON g1 FOR 5