basic-influence-roles

Basic Influence Roles (BIRs) ·

Detect and measure the basic role of influence each node plays within a directed network.

It supports a raw list of nodes, a Graphology DiGraph, as well as a method to be used in a distributed context for Big Data use cases.

This algorithm returns:

• The Basic Influence Role (BIR) of a node in a network
• The BIR's level
• The influence measure related to the role
• A global influence measure based on indegree and outdegree
• The influence ranking of the node

For in-depth theoretical details and more examples, please read the main repository intro.

Index of contents

All useful informations can be found in the following paragraphs:

• Installation
• How to use it
  • Detect Basic influence Roles
    • From a list of nodes
    • From a Graphology graph
    • In a distributed context
    • Outputs
  • Distributions of roles
• Testing
• Citing
• License

Installation

npm install basic-influence-roles

How to use it

Import BIRs package

Using import:

import BIRs from 'basic-influence-roles';

Using require:

const BIRs = require('basic-influence-roles');

Detect Basic Influence Roles

Methods to detect BIRs.

From a list of nodes

BIRs.detectFromNodes(nodes=Array[Object]);

Parameters

Field	Type	Required	Description
nodes	[{...}]	yes	An array of all nodes' data.
nodes[i].id	any	yes	The name or id of the node.
nodes[i].indegree	integer	yes	The number of incoming connections.
nodes[i].outdegree	integer	yes	The number of outcoming connections.

Example

// The list of nodes with indegree and outdegree
nodes = [
  {id: 1, indegree: 13, outdegree: 5},
  {id: 2, indegree: 3, outdegree: 8},
  {id: 3, indegree: 0, outdegree: 22},
  {id: 4, indegree: 16, outdegree: 19},
  {...}
];
// Measure the influence score and detect the basic influence roles
res = BIRs.detectFromNodes(nodes);

From a Graphology directed graph

Detect roles of a Graphology Directed Graph

BIRs.detectGraphology(G);

Parameters

Type	Required	Description
G	yes	A Graphology directed graph.

Example

const { DirectedGraph } = require('graphology');
// Create a directed graph
const G = new DirectedGraph({multi: false, allowSelfLoops: false});
// Add some nodes and edges
...
// Detect basic influence roles of nodes
res = BIRs.detectGraphology(G);

To use in a distributed context

In case of Big Data or Huge Networks you can distribute the load in this way:

BIRs.detect(indegree, outdegree, nodeCount, data);

Parameters

Field	Type	Required	Description
indegree	integer	yes	The number of incoming connections.
outdegree	integer	yes	The number of outcoming connections.
nodeCount	integer	yes	The total number of nodes.
data	boolean	no	If true returns indegree and outdegree.

Example

// Get the total count of nodes
nodeCount = 8586987087;
// For every node in a huge network (use here a distributed loop instead)
nodes.map(([indegree, outdegree]) => {
    // Get basic influence role of every node in network
    return BIRs.detect(indegree, outdegree, nodeCount, true);
});

Output

The output is a list of nodes reporting their id, role, role level, influence measure, influence ranking.

Field	Type	Description
id	any	The id of node.
role	string	The basic influence role.
roleInfluence	float	The influence magnitude related to the node's role.
roleLevel	string	The level of role, a role subcategory.
influence	float	A normalized influence score based on indegree and outdegree.
indegree	integer	The number of incoming connections.
outdegree	integer	The number of outcoming connections.
normalizedIndegree	float	The normalized number of incoming connections.
normalizedOutdegree	float	The normalized number of outcoming connections.
rank	integer	The normalized influence ranking based on the value of influence field.

Example

[
    {
        id: 4,
        role: 'hub',
        roleInfluence: 0.9210526315789473,
        roleLevel: 'strong',
        influence: 0.9210526315789473,
        indegree: 16,
        outdegree: 19,
        normalizedIndegree: 0.8421052631578947,
        normalizedOutdegree: 1.0,
        rank: 1
    },
    {
        id: 3,
        role: 'emitter',
        roleInfluence: 0.9473684210526315,
        roleLevel: 'strong',
        influence: 0.47368421052631576,
        indegree: 0,
        outdegree: 18,
        normalizedIndegree: 0.0,
        normalizedOutdegree: 0.9473684210526315
        rank: 2
    },
    ...
]

Get the distribution of Basic Influence Roles

Given a list of BIRs, can be calculated the distribution of BIRs in a network, as a normalized frequency between roles and also between their levels.

BIRs.distribution(data=[]);

Parameters

Field	Type	Required	Description
data	[{...}]	yes	The list of roles, the output of BIRs' detection methods.

Example

// Detect basic influence roles of nodes
data = BIRs.detectFromNodes([...])
// Detect the distribution of BIRs
res = BIRs.distribution(data)

Output

{
    reducer: {
        count: 12,
        frequency: 0.12,
        levels: {
            none: {count: 0, frequency: 0.0},
            branch: {count: 0, frequency: 0.0},
            weak: {count: 7, frequency: 0.07},
            strong: {count: 5, frequency: 0.05},
            top: {count: 0, frequency: 0.0}
        }
    },
    amplifier: {
        count: 13,
        frequency: 0.13,
        levels: {
            none: {count: 0, frequency: 0.0},
            branch: {count: 0, frequency: 0.0},
            weak: {count: 12, frequency: 0.12},
            strong: {count: 1, frequency: 0.01},
            top: {count: 0, frequency: 0.0}
        }
    },
    emitter: {
        count: 28,
        frequency: 0.28,
        levels: {
            none: {count: 0, frequency: 0.0},
            branch: {count: 18, frequency: 0.18},
            weak: {count: 10, frequency: 0.1},
            strong: {count: 0, frequency: 0.0},
            top: {count: 0, frequency: 0.0}
        }
    },
    ...
}

Tests

The package is battle tested with a coverage of 98%. Unit tests are inside the folder /test.

At first, install dev requirements:

npm install

To run all unit tests with coverage through nyc, type:

npm test

Citing

If you use this software in your work, please cite it as below:

Miceli, D. (2024). Basic Influence Roles (BIRs) [Computer software]. https://github.com/davidemiceli/basic-influence-roles

Or the BibTeX version:

@software{MiceliBasicInfluenceRoles2024,
  author = {Miceli, Davide},
  license = {MIT},
  month = mar,
  title = {{Basic Influence Roles (BIRs)}},
  url = {https://github.com/davidemiceli/basic-influence-roles},
  year = {2024}
}

License

Basic Influence Roles is an open source project available under the MIT license.