Metadata-Version: 2.4
Name: annnet
Version: 0.0.1
Summary: A Python tool to build, manipulate, and interoperate with flexible graph structures
Project-URL: Documentation, https://annnet.readthedocs.io/
Project-URL: Homepage, https://github.com/saezlab/annnet
Project-URL: Issues, https://github.com/saezlab/annnet/issues
Project-URL: Repository, https://github.com/saezlab/annnet
Author-email: Youssef Zerta <youssef.zerta@biomedtech.ueuromed.org>, Bottazzi Daniele <daniele.bottazzi@mail.polimi.it>, Denes Turei <turei.denes@gmail.com>
Maintainer-email: Bottazzi Daniele <daniele.bottazzi@mail.polimi.it>, Youssef Zerta <youssef.zerta@biomedtech.ueuromed.org>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: numpy>=2.2.6
Requires-Dist: polars>=0.20.0
Requires-Dist: scipy>=1.9.0
Provides-Extra: all
Requires-Dist: lxml>=5; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: networkx>=3.3; extra == 'all'
Requires-Dist: numcodecs>=0.12; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: pandas>=2.0.3; extra == 'all'
Requires-Dist: pyarrow>=14; extra == 'all'
Requires-Dist: python-igraph>=0.11; extra == 'all'
Requires-Dist: zarr>=2.18; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-jupyter>=0.25; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Provides-Extra: igraph
Requires-Dist: python-igraph>=0.11; extra == 'igraph'
Provides-Extra: networkx
Requires-Dist: networkx>=3.3; extra == 'networkx'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0.3; extra == 'pandas'
Provides-Extra: parquet
Requires-Dist: pyarrow>=14; extra == 'parquet'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == 'plot'
Provides-Extra: sbml
Requires-Dist: lxml>=5; extra == 'sbml'
Provides-Extra: tests
Requires-Dist: codecov-cli>=10.2.0; extra == 'tests'
Requires-Dist: coverage>=6.0; extra == 'tests'
Requires-Dist: diff-cover; extra == 'tests'
Requires-Dist: tox-gh>=1.5.0; extra == 'tests'
Requires-Dist: tox>=4.11; extra == 'tests'
Provides-Extra: zarr-io
Requires-Dist: numcodecs>=0.12; extra == 'zarr-io'
Requires-Dist: zarr>=2.18; extra == 'zarr-io'
Description-Content-Type: text/markdown

## Description

**annnet** is a lightweight, flexible, minimal-dependencies Python package for creating, manipulating, and interoperating with diverse graph data structures. It aims to be the connective tissue ("glue") between multiple graph ecosystems (NetworkX, igraph, graph-tool, etc.) while maintaining a clean and general-purpose internal representation.

---

## 📌 Description

annnet provides a unified interface for:

- Building general-purpose graphs (simple, directed, hyper, signed, etc.)
- Managing node/edge annotations
- Indexing and fast lookups
- Importing from or exporting to various tools and file formats

Its design supports complex workflows in data science, bioinformatics, and network theory — without locking you into a specific graph backend.

---

## ✅ Features

### General Graph Modeling
- Simple graphs, directed graphs, multigraphs
- Hypergraphs (via edge sets or higher-order relationships)
- Signed and weighted edges
- Rich node/edge annotations
- Efficient indexing and lookups

### Import Support
- CSV, JSON, and flat files
- Native import from existing objects:
  - `networkx.Graph`
  - `igraph.Graph`
  - `graph_tool.Graph`
  - `corneto.Graph`

### Export & Interoperability
- NetworkX (`to_networkx()`)
- igraph (`to_igraph()`)
- graph-tool (`to_graphtool()`)
- [CORNETO](https://corneto.org/)
- CSV, JSON, and custom serializations

### Backend-specific Integration (if installed)

If `networkx` is installed, you can call any NetworkX algorithm directly using dot notation:

```python
centrality = G.nx.degree_centrality()
```
**How it works:**

1. annnet converts `G` to a NetworkX object on demand, abstracting away all the non-needed attributes.
2. Runs the algorithm _as-is_.
3. Returns results directly, syncing any graph changes back to the internal representation of the `gg.Graph`.

This allows you to access the full power of NetworkX algorithms with zero boilerplate.

---

## 🛠️ Installation
To install annnet, you can use pip:

```bash
pip install annnet
```

Optional dependencies for extended functionality:

```bash
pip install annnet[networkx,igraph]
pip install annnet[graph-tool]
pip install annnet[corneto]
```

---

## 🚀 Quick Start

```python
import annnet as gg

# Create a new graph
G = gg.Graph(directed=True, backend="corneto")

# Add nodes and edges
G.add_node("A", type="gene")
G.add_node("B", type="protein")
G.add_edge("A", "B", sign="+", source="literature")

# Run a NetworkX algorithm (if installed)
path = G.nx.shortest_path(source="A", target="B")

# Export to JSON
G.to_json("graph.json")
```

---

## 📦 Refined Package Structure
The package is organized to separate core functionality, I/O operations, adapters for external libraries, and algorithms. This modular design allows for easy extension and maintenance.

```
annnet/
│
├── __init__.py                # Public API surface, version, re-exports
├── _version.py                # Single source of truth for __version__
│
├── core/                      # Core, always-installed logic
│   ├── __init__.py
│   ├── _base.py               # BaseGraph class and common interfaces 
│   ├── _graph.py              # Graph class and internal state manager
│   ├── structure.py           # Core data structures (nodes, edges, incidence)
│   ├── metadata.py            # Node/edge attribute store and access helpers
│   ├── views.py               # Subgraph views, shallow/deep copies
│   └── state.py               # Graph history, change tracking, and lazy loading
│
├── io/                        # Loaders and writers for files
│   ├── __init__.py
│   ├── csv.py                 # CSV format (edge list, node table)
│   ├── json.py                # JSON or JSONL parsing (streamable)
│   ├── registry.py            # Entry point registration for loaders/dumpers
│   └── utils.py               # Format detection, path helpers
│
├── adapters/                  # Lazy integration with external libraries
│   ├── __init__.py
│   ├── _base.py               # AbstractAdapter, adapter interface
│   ├── _proxy.py              # Tiny forwarding proxy
│   ├── manager.py             # Adapter registry and lazy bridge logic
│   ├── networkx.py            # If available: convert, cache, sync with NetworkX
│   ├── igraph.py              # If available
│   ├── graphtool.py           # If available
│   └── corneto.py             # If available
│
├── algorithms/                # Pure-python algorithms using core only
│   ├── __init__.py
│   └── traversal.py           # BFS/DFS etc.
│
└── utils/                     # Generic helpers not tied to graph structure
    ├── validation.py
    ├── typing.py
    └── config.py              # Global options, logging, toggles
```

---

## ⚙️ Internal Design
annnet intelligently adapts its internal representation for performance and compatibility:

- Chooses between edge lists, incidence matrices, and adjacency dicts automatically
- Keeps metadata (node/edge attributes) separate from core structure
- Lazy construction of external library representations (e.g., NetworkX) only when needed
- Copy-on-write design for subgraphs and structural mutations

---

## 🧭  Philosophy
annnet vis designed with these principles in mind:

- **Simple**, consistent interface for all graph types
- **Interoperability-first**: integrate, don’t replace
- **Performance-aware**, not performance-obsessed
- **Extendable** and modular, not monolithic

---

## 📜 License
annnet is licensed under the BSD-3 License. See the [LICENSE](LICENSE) file for details.

