mirror of
https://github.com/metabarcoding/obitools4.git
synced 2026-04-30 12:00:39 +00:00
Eric Coissac
8c7017a99d
- Update obioptions.Version from "Release 4.4.29" to "/v/ Release v5" - Update version.txt from 4.29 → .30 (automated by Makefile)
88 lines
3.9 KiB
Markdown
88 lines
3.9 KiB
Markdown
# `obigraph`: Semantic Overview of Public Features
|
|
|
|
The `obigraph` package delivers a lightweight, type-safe graph modeling toolkit in Go—optimized for performance and visualization-ready output. Built around two core abstractions (`Graph` and `GraphBuffer`), it supports both static graph construction (for batch processing) and high-throughput streaming ingestion (via buffered channels), while enabling customizable vertex/edge semantics, degree-based filtering, and GML export with visual styling.
|
|
|
|
---
|
|
|
|
## Core Graph Type: `Graph[V, T]`
|
|
|
|
### Generic Structure
|
|
- **Type Parameters**:
|
|
- `V`: Vertex type (arbitrary comparable Go value).
|
|
- `T`: Edge data payload (e.g., weight, label, metadata).
|
|
- **Internal Representation**:
|
|
- Forward adjacency: `map[V]map[V]T` (outgoing edges).
|
|
- Reverse adjacency: `map[V]map[V]T` (incoming edges), enabling bidirectional traversal.
|
|
|
|
### Edge Management
|
|
- **Undirected Edges**:
|
|
- `AddEdge(src, dst V, data T)`: Inserts symmetric links (both directions).
|
|
- **Directed Edges**:
|
|
- `AddDirectedEdge(src, dst V, data T)`: Inserts one-way link.
|
|
- `SetAsDirectedEdge(src, dst V)`: Converts existing undirected edge to directed by deleting reverse link.
|
|
|
|
### Graph Queries
|
|
- **Neighbors**:
|
|
- `Neighbors(v V) []V`: Returns all vertices reachable *from* `v` (successors).
|
|
- **Parents**:
|
|
- `Parents(v V) []V`: Returns all vertices with edges *to* `v` (predecessors).
|
|
- **Degrees**:
|
|
- `Degree(v V) int`: Out-degree (size of outgoing adjacency).
|
|
- `ParentDegree(v V) int`: In-degree (size of incoming adjacency).
|
|
|
|
### Customization Hooks
|
|
- **Vertex Weight**:
|
|
- `func VertexWeight(v V) float64` (default: constant weight = `1.0`).
|
|
- **Edge Weight**:
|
|
- `func EdgeWeight(src, dst V) float64` (default: constant weight = `1.0`).
|
|
- **Vertex Labeling**:
|
|
- `func VertexId(v V) string` (default: `"V%d"` with auto-incrementing index).
|
|
|
|
### GML Export
|
|
- **In-Memory Generation**:
|
|
- `Gml(w io.Writer, opts ...Option) error`: Renders GML to any writer.
|
|
- **File Output**:
|
|
- `WriteGmlFile(filename string, opts ...Option) error`: Writes GML to disk.
|
|
- **Styling Options** (via `text/template`):
|
|
- Directed/undirected mode (`Directed: bool`).
|
|
- Degree-based filtering (`MinDegree int`): Omits vertices below threshold.
|
|
- Visual layout:
|
|
- Shape = `circle` if vertex weight ≥ `Threshold`, else `rectangle`.
|
|
- Size ∝ sqrt(vertex weight).
|
|
|
|
> ⚠️ Errors during template parsing or I/O cause panics (fail-fast design).
|
|
|
|
---
|
|
|
|
## Streaming Graph Builder: `GraphBuffer[V, T]`
|
|
|
|
### Asynchronous Edge Ingestion
|
|
- **Channel-Based Protocol**:
|
|
- Edges are enqueued via `AddEdge(src, dst V)` / `AddDirectedEdge(...)` → pushes to internal buffered channel.
|
|
- Background goroutine consumes edges and mutates underlying `Graph[V, T]`.
|
|
|
|
### Non-Blocking API
|
|
- All edge-addition methods return immediately (no synchronization on mutation).
|
|
- Ideal for producer-consumer patterns where multiple goroutines feed edges.
|
|
|
|
### Lifecycle Management
|
|
- **Initialization**:
|
|
- `NewGraphBuffer(cap int) *GraphBuffer[V, T]`: Starts worker goroutine and allocates channel.
|
|
- **Shutdown**:
|
|
- `Close()`: Closes ingestion channel → signals worker to terminate gracefully.
|
|
|
|
### GML Export (Same as `Graph`)
|
|
- Supports identical options (`MinDegree`, `Directed`, etc.) via inherited methods.
|
|
- Enables exporting *final* state after streaming completes.
|
|
|
|
> ⚠️ **Concurrency Note**:
|
|
> - `AddEdge` is *not* safe for concurrent calls without external buffering (e.g., use channel per producer).
|
|
> - The buffer itself handles internal mutation safety via sequential processing.
|
|
|
|
---
|
|
|
|
## Use Cases
|
|
- **Batch Graph Construction**: `Graph` for offline analysis, static topology generation.
|
|
- **Real-Time Processing**: `GraphBuffer` for event-driven systems (e.g., social feeds, telemetry streams).
|
|
- **Visualization Prep**: GML export supports tools like Graphviz/Cytoscape with minimal styling overhead.
|