xianggebenben / cosasi

COntagion Simulation And Source Identification: a Python package for graph diffusion source inference

cosasi: Graph Diffusion Source Inference in Python

cosasi (COntagion Simulation And Source Identification) is a Python package for graph diffusion source inference, allowing users to:

• perform and evaluate source inference using standard techniques from literature,
• contribute innovative localization methods to a growing core library, and
• benchmark new techniques against a battery of comparable schemes.

Table of Contents

• Table of Contents
• Installation
• Getting Started
• Code Snippet
• Testing
• Contributions
• Citing
• Support
• Contact
• License

Installation

Installation via PyPI

pip install cosasi

Installation via GitHub

Clone the repo from here (this repo).

Install requirements:

pip install -r requirements.txt

Getting Started

Once cosasi is installed, feel free to review our tutorial introducing major functionality. Official documentation, including a detailed API reference, is available on Read the Docs.

Code Snippet

Above: Carbon image of example code snippet; copy-and-paste-able version below.

import networkx as nx
import cosasi

G = nx.fast_gnp_random_graph(100, 0.25)
contagion = cosasi.StaticNetworkContagion(
   G=G,
   model="si",
   infection_rate=0.01,
   number_infected=3,
)
contagion.forward(100)
I = contagion.get_infected_subgraph(step=15)
result = cosasi.source_inference.multiple_source.netsleuth(G=G, I=I)
result.evaluate(contagion.get_source())

Testing

Extensive unit testing is employed throughout, with ~97% code coverage.

If you've cloned our repo from GitHub, you can cd into the root directory and run pytest via coverage:

    coverage run -m pytest

To read the .coverage file:

    coverage report

Contributions

We’d love your help! If you’d like to make an addition or improvement, please submit a pull request consisting of an atomic commit and a brief message describing your contribution.

Our contributor guide is here, and we itemize a few areas of development we’d like to prioritize for the future of cosasi here. If you find something wrong, please submit a bug report to the issue tracker. For other questions or comments, feel free to contact us directly.

Citing

If you found cosasi helpful in your work, please consider citing it with:

@article{McCabe2022joss,
  doi = {10.21105/joss.04894},
  url = {https://doi.org/10.21105/joss.04894},
  year = {2022},
  publisher = {The Open Journal},
  volume = {7},
  number = {80},
  pages = {4894},
  author = {Lucas H. McCabe},
  title = {cosasi: Graph Diffusion Source Inference in Python}, journal = {Journal of Open Source Software}
}

McCabe, L. H., (2022). cosasi: Graph Diffusion Source Inference in Python. Journal of Open Source Software, 7(80), 4894, https://doi.org/10.21105/joss.04894

Support

cosasi was developed in Forge, the technology accelerator of the Logistics Management Institute.

Contact

Questions? Reach out:

• Lucas (email)

License

MIT