Documentation (#3)

* jupyter and some documentation updates

* jupyter and some documentation updates

* Documentation generated

* Documentation

---------

Co-authored-by: Edyta Frąszczak <[email protected]>

CHANGELOG.md

@@ -3,6 +3,6 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2024-07-08
+## [0.1.0] - 2024-07-05
 ### Added
 - NSDlib version 0.1.0 release

docs/conf.py

@@ -17,7 +17,6 @@
 # -- Project information -----------------------------------------------------
 now = datetime.datetime.now()
 
-
 project = "NSDLib"
 author = "Damian Frąszczak, Edyta Frąszczak"
 copyright = f"{now.year}, {author}"

docs/files/CODE_OF_CONDUCT.md

@@ -0,0 +1,43 @@
+# Code of Conduct for the Network Source Detection Library) Project
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery and unwelcome sexual attention or advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at [INSERT EMAIL ADDRESS]. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality regarding the reporter of an incident.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.

docs/files/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to NSDLib
+
+We warmly welcome contributions to NSDLib! This document provides guidelines for contributing to this project. By participating in this project, you agree to abide by its terms.
+
+## Table of Contents
+- [How to Contribute](#how-to-contribute)
+- [Local Development Setup](#local-development-setup)
+- [Releasing a New Version](#releasing-a-new-version)
+- [Pre-commit Hooks](#pre-commit-hooks)
+
+## How to Contribute
+
+### Reporting Bugs and Requesting Features
+
+- **Bug Reports**: Please use the [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md) to report any bugs. Provide as much detail as possible to help us understand and fix the issue.
+- **Feature Requests**: For proposing new features or enhancements, use the [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md). Describe the feature, its benefits, and possible implementation if you have one in mind.
+
+### Coding Style
+
+- **PEP 8**: All Python code must adhere to the [PEP 8 style guide](https://www.python.org/dev/peps/pep-0008/), except where explicitly mentioned.
+- **Comments and Docstrings**: Use comments and docstrings to explain the purpose of complex code blocks. Follow the [PEP 257](https://www.python.org/dev/peps/pep-0257/) docstring conventions.
+
+### Implementation Requirements
+
+- **Source Detection Method Implementation**:
+  - Each new method must be implemented in a separate file within the `nsdlib/algorithms` directory in appropriate package according to its intended purpose e.g. reconstruction algorithm should be placed in `reconstruction` package.
+  - The file name should match the method's name.
+  - Each file must contain a single function, named after the new method name.
+  - Each alg function must be exposed in the `nsdlib/algorithms` package to be accessible for external use.
+  - Add an entry for the new alg in the appropiate taxonomy class, e.g. for reconstruction algorithm new entry should be placed into `PropagationReconstructionAlgorithm` enum to ensure it's recognized and accessible through a standardized interface.
+
+- **Testing**:
+  - Contributions must include tests covering the new functionality. We require at least 80% test coverage for changes.
+  - Use the `pytest` framework for writing tests.
+
+- **Documentation**:
+  - Update the project documentation to reflect the addition of new method or any other significant changes.
+  - Ensure that examples, usage guides, and API documentation are clear and updated.
+
+### Making Changes
+
+1. **Create an Issue**: For every change, whether a bug fix or a feature implementation, please open a new issue. This helps us keep track of what's being worked on and discuss potential changes before the development work starts.
+2. **Follow the Style Guide and Contribution Requirements**: Adhere to the [Coding Style](#coding-style) and [Contribution Requirements](#contribution-requirements).
+3. **Use Pre-commit Hooks**: This project uses pre-commit hooks to ensure code style and quality. Run `pre-commit install` after cloning the repository to set up the hooks locally. For more, check [Pre-commit Hooks](#pre-commit-hooks).
+4. **Submit a Pull Request**: Once you're ready, submit a pull request linked to the issue you've created. Describe your changes clearly in the PR description.
+
+
+## Local development setup
+
+By default venv is used to work on the project. After creating venv, install the requirements:
+
+```bash
+pip install -r requirements.txt
+pip install -r requirements.dev.txt
+```
+and you are ready to go.
+
+## Release a version
+
+- Merge your PR into **`main`**
+- Update changelog in CHANGELOG.md
+- Change the version in src/nsdlib/version.py
+- Commit. `git commit -m 'Release version x.y.z'`
+- Tag the commit. `git tag -a x.y.z -m 'Release version x.y.z'`
+- Push (do not forget --tags). `git push origin master --tags`
+- Release will be created automatically by GitHub Actions
+
+
+## Pre-commit Hooks
+
+This project supports [**pre-commit**](https://pre-commit.com/). To use it please install it
+in the `pip install pre-commit` and then run `pre-commit install` and you are ready to go.
+Bunch of checks will be executed before commit and files will be formatted correctly.
+
+Pre-commit works on staged files while commiting. To run it without a command one should run `pre-commit run`. Changes has to be staged.
+
+To run pre-commit hooks on all changes in the branch:
+
+1.  Sync branch with main
+1.  Run `git diff --name-only --diff-filter=MA origin/master | xargs pre-commit run --files`
+
+For branches that are not based on `master` you might replace `origin/master` with `origin/{your_branch}`

docs/files/INTRODUCTION.md

@@ -0,0 +1,11 @@
+# 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.
+
+## Overview
+
+NSDLib is a complex library designed for easy integration into existing projects. It aims to be a comprehensive repository
+of source detection methods, outbreak detection techniques, and propagation graph reconstruction tools. Researchers worldwide are encouraged to contribute and utilize this library,
+facilitating the development of new techniques to combat misinformation and improve propagation analysis.
+Each  year, new techniques are introduced through scientific papers, often with only pseudo-code descriptions, making it
+difficult for researchers to evaluate and compare them with existing methods. NSDlib tries to bridge this gap and enhance researchers to put their implementations here.

docs/files/QUICK_START.md

@@ -0,0 +1,114 @@
+# 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:
+
+```bash
+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.
+
+```python
+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:
+
+```python
+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:
+
+```python
+
+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](nsdlib.ipynb).