# Basic Influence Roles (BIRs) · [](https://github.com/davidemiceli/basic-influence-roles/blob/master/LICENSE) [](https://github.com/davidemiceli/basic-influence-roles/pulls)
_**Detect and measure the basic role of influence each node plays within a directed network.**_
It supports a raw list of nodes, a NetworkX 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**](https://github.com/davidemiceli/basic-influence-roles/blob/main/README.md).
## Index of contents
All useful informations can be found in the following paragraphs:
- [**Installation**](#installation)
- [**How to use it**](#how-to-use-it)
- [**Detect Basic influence Roles**](#detect-birs)
- [**From a list of nodes**](#list-of-nodes)
- [**From a NetworkX graph**](#networkx-graph)
- [**In a distributed context**](#distributed-context)
- [**Outputs**](#results)
- [**Distributions of roles**](#distribution-birs)
- [**Testing**](#testing)
- [**Citing**](#citing)
- [**License**](#license)
## Installation <a name="installation"></a>
```shell
pip install basic-influence-roles
```
## How to use it <a name="how-to-use-it"></a>
Import BIRs package
```python
import BIRs
```
## Detect Basic Influence Roles <a name="detect-birs"></a>
Methods to detect BIRs.
### From a list of nodes <a name="list-of-nodes"></a>
```python
BIRs.detect_from_nodes(nodes=List[Dict])
```
#### Parameters
Field | Type | Required | Description
--- | --- | --- | ---
`nodes` | *[{...}]* | yes | A list of all nodes' data as dict.
`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*
```python
# 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.detect_from_nodes(nodes)
```
### From a NetworkX graph <a name="networkx-graph"></a>
```python
BIRs.detect_nx(nx.DiGraph)
```
#### Parameters
Type | Required | Description
--- | --- | ---
*nx.DiGraph* | yes | A NetworkX directed graph.
##### *Example*
```python
# Create a random directed graph
G = nx.erdos_renyi_graph(100, 0.01, directed=True)
# Remove possible self-loop edges
G.remove_edges_from(nx.selfloop_edges(G))
# Detect basic influence roles of nodes
res = BIRs.detect_nx(G)
```
### To use in a distributed context <a name="distributed-context"></a>
In case of Big Data or Huge Networks you can distribute the load in this way:
```python
BIRs.detect(indegree, outdegree, node_count)
```
#### Parameters
Field | Type | Required | Description
--- | --- | --- | ---
`indegree` | *integer* | yes | The number of incoming connections.
`outdegree` | *integer* | yes | The number of outcoming connections.
`node_count` | *integer* | yes | The total number of nodes.
`data` | *boolean* | no | If `True` returns indegree and outdegree.
##### *Example*
```python
# Get the total count of nodes
node_count = 8586987087
# For every node in a huge network (use here a distributed loop instead)
for indegree, outdegree in nodes:
# Get basic influence role of every node in network
res = BIRs.detect(indegree, outdegree, node_count, 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.
`role_influence` | *float* | The influence magnitude related to the node's role.
`role_level` | *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.
`normalized_indegree` | *float* | The normalized number of incoming connections.
`normalized_outdegree` | *float* | The normalized number of outcoming connections.
`rank` | *integer* | The normalized influence ranking based on the value of *influence* field.
##### *Example*
```python
[
{
'id': 4,
'role': 'hub',
'role_influence': 0.9210526315789473,
'role_level': 'strong',
'influence': 0.9210526315789473,
'indegree': 16,
'outdegree': 19,
'normalized_indegree': 0.8421052631578947,
'normalized_outdegree': 1.0,
'rank': 1
},
{
'id': 3,
'role': 'emitter',
'role_influence': 0.9473684210526315,
'role_level': 'strong',
'influence': 0.47368421052631576,
'indegree': 0,
'outdegree': 18,
'normalized_indegree': 0.0,
'normalized_outdegree': 0.9473684210526315
'rank': 2
},
...
]
```
## Get the distribution of Basic Influence Roles <a name="distribution-birs"></a>
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.
```python
BIRs.distribution(data=[])
```
#### Parameters
Field | Type | Required | Description
--- | --- | --- | ---
`data` | *[{...}]* | yes | The list of roles, the output of BIRs' detection methods.
##### *Example*
```python
# Create a random directed graph
G = nx.erdos_renyi_graph(100, 0.01, directed=True)
# Remove possible self-loop edges
G.remove_edges_from(nx.selfloop_edges(G))
# Detect basic influence roles of nodes
data = BIRs.detect_nx(G)
# Detect the distribution of BIRs
res = BIRs.distribution(data)
```
#### Output
```python
{
'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 <a name="testing"></a>
The package is battle tested with a coverage of 98%. Unit tests are inside the folder `/test`.
At first, install dev requirements:
```shell
pip install -r requirements-dev.txt
```
To run all unit tests with coverage, type:
```shell
PYTHONPATH=src python -m coverage run --source=src -m unittest discover test -v
```
Or run the bash script:
```shell
./test.sh
```
To run the coverage report:
```shell
coverage report -m
```
## Citing <a name="citing"></a>
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:
```bibtex
@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 <a name="license"></a>
Basic Influence Roles is an open source project available under the [MIT license](https://github.com/davidemiceli/basic-influence-roles/blob/master/LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "basic-influence-roles",
"maintainer": "Davide Miceli",
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": null,
"keywords": "graph, network, clustering, complex networks, network analysis, social network analysis, network science, influence network, network dynamics, social influence, social role, social sciences",
"author": "Davide Miceli",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/df/20/edd8af5b5204189d04072c197b03a64c11a1c9805b8db06f3f6437724170/basic-influence-roles-1.0.5.tar.gz",
"platform": null,
"description": "# Basic Influence Roles (BIRs) · [](https://github.com/davidemiceli/basic-influence-roles/blob/master/LICENSE) [](https://github.com/davidemiceli/basic-influence-roles/pulls)\n\n_**Detect and measure the basic role of influence each node plays within a directed network.**_ \n\nIt supports a raw list of nodes, a NetworkX DiGraph, as well as a method to be used in a distributed context for Big Data use cases.\n\nThis algorithm returns:\n- The Basic Influence Role (BIR) of a node in a network\n- The BIR's level\n- The influence measure related to the role\n- A global influence measure based on indegree and outdegree\n- The influence ranking of the node\n\nFor in-depth theoretical details and more examples, please read the main repository [**intro**](https://github.com/davidemiceli/basic-influence-roles/blob/main/README.md).\n\n## Index of contents\n\nAll useful informations can be found in the following paragraphs:\n- [**Installation**](#installation)\n- [**How to use it**](#how-to-use-it)\n - [**Detect Basic influence Roles**](#detect-birs)\n - [**From a list of nodes**](#list-of-nodes)\n - [**From a NetworkX graph**](#networkx-graph)\n - [**In a distributed context**](#distributed-context)\n - [**Outputs**](#results)\n - [**Distributions of roles**](#distribution-birs)\n- [**Testing**](#testing)\n- [**Citing**](#citing)\n- [**License**](#license)\n\n## Installation <a name=\"installation\"></a>\n```shell\npip install basic-influence-roles\n```\n\n## How to use it <a name=\"how-to-use-it\"></a>\n\nImport BIRs package\n\n```python\nimport BIRs\n```\n\n## Detect Basic Influence Roles <a name=\"detect-birs\"></a>\n\nMethods to detect BIRs.\n\n### From a list of nodes <a name=\"list-of-nodes\"></a>\n\n```python\nBIRs.detect_from_nodes(nodes=List[Dict])\n```\n\n#### Parameters\nField | Type | Required\t| Description\n--- | --- | --- | ---\n`nodes`\t| *[{...}]* | yes | A list of all nodes' data as dict.\n`nodes[i]['id']` | *any*\t| yes | The name or id of the node.\n`nodes[i]['indegree']` | *integer* | yes | The number of incoming connections.\n`nodes[i]['outdegree']` | *integer* | yes\t| The number of outcoming connections.\n\n##### *Example*\n```python\n# The list of nodes with indegree and outdegree\nnodes = [\n {'id': 1, 'indegree': 13, 'outdegree': 5},\n {'id': 2, 'indegree': 3, 'outdegree': 8},\n {'id': 3, 'indegree': 0, 'outdegree': 22},\n {'id': 4, 'indegree': 16, 'outdegree': 19},\n {...}\n]\n# Measure the influence score and detect the basic influence roles\nres = BIRs.detect_from_nodes(nodes)\n```\n\n### From a NetworkX graph <a name=\"networkx-graph\"></a>\n\n```python\nBIRs.detect_nx(nx.DiGraph)\n```\n\n#### Parameters\nType | Required\t| Description\n--- | --- | ---\n*nx.DiGraph* | yes | A NetworkX directed graph.\n\n##### *Example*\n```python\n# Create a random directed graph\nG = nx.erdos_renyi_graph(100, 0.01, directed=True)\n# Remove possible self-loop edges\nG.remove_edges_from(nx.selfloop_edges(G))\n# Detect basic influence roles of nodes\nres = BIRs.detect_nx(G)\n```\n\n### To use in a distributed context <a name=\"distributed-context\"></a>\n\nIn case of Big Data or Huge Networks you can distribute the load in this way:\n```python\nBIRs.detect(indegree, outdegree, node_count)\n```\n\n#### Parameters\nField | Type | Required\t| Description\n--- | --- | --- | ---\n`indegree` | *integer* | yes | The number of incoming connections.\n`outdegree` | *integer* | yes | The number of outcoming connections.\n`node_count` | *integer* | yes | The total number of nodes.\n`data` | *boolean* | no | If `True` returns indegree and outdegree.\n\n##### *Example*\n```python\n# Get the total count of nodes\nnode_count = 8586987087\n# For every node in a huge network (use here a distributed loop instead)\nfor indegree, outdegree in nodes:\n # Get basic influence role of every node in network\n res = BIRs.detect(indegree, outdegree, node_count, True)\n```\n\n### Output\n\nThe output is a list of nodes reporting their id, role, role level, influence measure, influence ranking.\n\nField | Type | Description\n--- | --- | ---\n`id` | *any* | The id of node.\n`role` | *string* | The basic influence role.\n`role_influence` | *float* | The influence magnitude related to the node's role.\n`role_level` | *string* | The level of role, a role subcategory.\n`influence` | *float* | A normalized influence score based on indegree and outdegree.\n`indegree` | *integer* | The number of incoming connections.\n`outdegree` | *integer* | The number of outcoming connections.\n`normalized_indegree` | *float* | The normalized number of incoming connections.\n`normalized_outdegree` | *float* | The normalized number of outcoming connections.\n`rank` | *integer* | The normalized influence ranking based on the value of *influence* field.\n\n##### *Example*\n```python\n[\n {\n 'id': 4,\n 'role': 'hub',\n 'role_influence': 0.9210526315789473,\n 'role_level': 'strong',\n 'influence': 0.9210526315789473,\n 'indegree': 16,\n 'outdegree': 19,\n 'normalized_indegree': 0.8421052631578947,\n 'normalized_outdegree': 1.0,\n 'rank': 1\n },\n {\n 'id': 3,\n 'role': 'emitter',\n 'role_influence': 0.9473684210526315,\n 'role_level': 'strong',\n 'influence': 0.47368421052631576,\n 'indegree': 0,\n 'outdegree': 18,\n 'normalized_indegree': 0.0,\n 'normalized_outdegree': 0.9473684210526315\n 'rank': 2\n },\n ...\n]\n```\n\n## Get the distribution of Basic Influence Roles <a name=\"distribution-birs\"></a>\n\nGiven 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.\n\n```python\nBIRs.distribution(data=[])\n```\n\n#### Parameters\nField | Type | Required\t| Description\n--- | --- | --- | ---\n`data` | *[{...}]* | yes | The list of roles, the output of BIRs' detection methods.\n\n##### *Example*\n```python\n# Create a random directed graph\nG = nx.erdos_renyi_graph(100, 0.01, directed=True)\n# Remove possible self-loop edges\nG.remove_edges_from(nx.selfloop_edges(G))\n# Detect basic influence roles of nodes\ndata = BIRs.detect_nx(G)\n# Detect the distribution of BIRs\nres = BIRs.distribution(data)\n```\n\n#### Output\n```python\n{\n 'reducer': {\n 'count': 12,\n 'frequency': 0.12,\n 'levels': {\n 'none': {'count': 0, 'frequency': 0.0},\n 'branch': {'count': 0, 'frequency': 0.0},\n 'weak': {'count': 7, 'frequency': 0.07},\n 'strong': {'count': 5, 'frequency': 0.05},\n 'top': {'count': 0, 'frequency': 0.0}\n }\n },\n 'amplifier': {\n 'count': 13,\n 'frequency': 0.13,\n 'levels': {\n 'none': {'count': 0, 'frequency': 0.0},\n 'branch': {'count': 0, 'frequency': 0.0},\n 'weak': {'count': 12, 'frequency': 0.12},\n 'strong': {'count': 1, 'frequency': 0.01},\n 'top': {'count': 0, 'frequency': 0.0}\n }\n },\n 'emitter': {\n 'count': 28,\n 'frequency': 0.28,\n 'levels': {\n 'none': {'count': 0, 'frequency': 0.0},\n 'branch': {'count': 18, 'frequency': 0.18},\n 'weak': {'count': 10, 'frequency': 0.1},\n 'strong': {'count': 0, 'frequency': 0.0},\n 'top': {'count': 0, 'frequency': 0.0}\n }\n },\n ...\n}\n```\n\n## Tests <a name=\"testing\"></a>\n\nThe package is battle tested with a coverage of 98%. Unit tests are inside the folder `/test`.\n\nAt first, install dev requirements:\n```shell\npip install -r requirements-dev.txt\n```\n\nTo run all unit tests with coverage, type:\n```shell\nPYTHONPATH=src python -m coverage run --source=src -m unittest discover test -v\n```\n\nOr run the bash script:\n```shell\n./test.sh\n```\n\nTo run the coverage report:\n```shell\ncoverage report -m\n```\n\n## Citing <a name=\"citing\"></a>\n\nIf you use this software in your work, please cite it as below:\n> Miceli, D. (2024). Basic Influence Roles (BIRs) [Computer software]. https://github.com/davidemiceli/basic-influence-roles\n\nOr the BibTeX version:\n\n```bibtex\n@software{MiceliBasicInfluenceRoles2024,\n author = {Miceli, Davide},\n license = {MIT},\n month = mar,\n title = {{Basic Influence Roles (BIRs)}},\n url = {https://github.com/davidemiceli/basic-influence-roles},\n year = {2024}\n}\n```\n\n## License <a name=\"license\"></a>\n\nBasic Influence Roles is an open source project available under the [MIT license](https://github.com/davidemiceli/basic-influence-roles/blob/master/LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "Detect and measure the Basic Influence Role each node holds within a Directed Network.",
"version": "1.0.5",
"project_urls": {
"Homepage": "https://github.com/davidemiceli/basic-influence-roles",
"Issues": "https://github.com/davidemiceli/basic-influence-roles/issues"
},
"split_keywords": [
"graph",
" network",
" clustering",
" complex networks",
" network analysis",
" social network analysis",
" network science",
" influence network",
" network dynamics",
" social influence",
" social role",
" social sciences"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ef80cee190fedc46820fed6f1dd905d5752ca48326c59e2328bf3239b8a7969a",
"md5": "ba58733265ba99a7ff05d51a5fe4b2aa",
"sha256": "445c0847f73f89a29cb4e7347c70890943871ddf324e235e5aa633b917d1289c"
},
"downloads": -1,
"filename": "basic_influence_roles-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba58733265ba99a7ff05d51a5fe4b2aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 5873,
"upload_time": "2024-03-22T07:27:14",
"upload_time_iso_8601": "2024-03-22T07:27:14.522120Z",
"url": "https://files.pythonhosted.org/packages/ef/80/cee190fedc46820fed6f1dd905d5752ca48326c59e2328bf3239b8a7969a/basic_influence_roles-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "df20edd8af5b5204189d04072c197b03a64c11a1c9805b8db06f3f6437724170",
"md5": "c4be308d12ce3303f289a637debe2d98",
"sha256": "fd68f36485d3f53da4c010c9f89d705ccdec2761eddfc8dd7431dbe8f039b386"
},
"downloads": -1,
"filename": "basic-influence-roles-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "c4be308d12ce3303f289a637debe2d98",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 6990,
"upload_time": "2024-03-22T07:27:16",
"upload_time_iso_8601": "2024-03-22T07:27:16.236096Z",
"url": "https://files.pythonhosted.org/packages/df/20/edd8af5b5204189d04072c197b03a64c11a1c9805b8db06f3f6437724170/basic-influence-roles-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-22 07:27:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "davidemiceli",
"github_project": "basic-influence-roles",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "basic-influence-roles"
}
JSON
