graphizy 0.1.5

A graph maker for computational geometry and network visualization

Graphizy

A powerful graph maker for computational geometry and network visualization, specializing in multiple graph types and memory-enhanced analysis.

Figure: Positions are converted to graphs in just a few milliseconds for hundreds of individuals using OpenCV.
Graph analytics are accessible in real time by interfacing with igraph.

🎯 Key Features

📊 Graph Construction Types

• 🔺 Delaunay Triangulation: Optimal triangular meshes from point sets
• 📡 Proximity Graphs: Connect nearby points based on distance thresholds
• 🔗 K-Nearest Neighbors: Connect each point to its k closest neighbors
• 🌲 Minimum Spanning Tree: Minimal connected graph with shortest total edge length
• 🔵 Gabriel Graph: Geometric proximity graph (subset of Delaunay triangulation)
• 🧠 Memory-Enhanced Graphs: Any graph type + historical connection tracking

🧮 Graph Analysis

• igraph Integration: Full access to igraph's powerful analytics
• Comprehensive API: Call any igraph method with error handling
• Real-time Statistics: Vertex count, edge count, connectivity, clustering, centrality

🎨 Visualization & Design

• Flexible Configuration: Runtime-configurable parameters using dataclasses
• Multiple Output Formats: Save as images or display interactively with OpenCV
• Memory Visualization: Age-based edge coloring for temporal analysis
• Command Line Interface: Easy-to-use CLI for common operations
• Interactive Demos: Real-time Brownian motion simulation with graph evolution

🔧 Technical Excellence

• Robust Error Handling: Detailed exceptions and validation
• Performance Monitoring: Built-in timing and optimization tracking
• Memory Management: Configurable connection history with aging
• Type Safety: Full type hints and dataclass configuration

🚀 Installation

pip install graphizy

Or for development:

git clone https://github.com/cfosseprez/graphizy.git
cd graphizy
pip install -e .

⚡ Quick Start

Basic Graph Creation

import numpy as np
from graphizy import Graphing, GraphizyConfig, generate_positions

# Generate random points
positions = generate_positions(800, 800, 100)
particle_ids = np.arange(len(positions))
data = np.column_stack((particle_ids, positions))

# Create grapher with configuration
config = GraphizyConfig()
config.graph.dimension = (800, 800)
grapher = Graphing(config=config)

# Create different graph types
delaunay_graph = grapher.make_delaunay(data)
proximity_graph = grapher.make_proximity(data, proximity_thresh=50.0)
knn_graph = grapher.make_knn(data, k=4)  # Connect to 4 nearest neighbors
mst_graph = grapher.make_mst(data)       # Minimum spanning tree
gabriel_graph = grapher.make_gabriel(data)  # Gabriel graph

# Visualize and save
delaunay_image = grapher.draw_graph(delaunay_graph)
grapher.save_graph(delaunay_image, "delaunay.jpg")
# Or display interactively
grapher.show_graph(delaunay_image, "Delaunay Triangulation")

# Get comprehensive statistics
info = grapher.get_graph_info(delaunay_graph)
print(f"Graph: {info['vertex_count']} vertices, {info['edge_count']} edges")
print(f"Density: {info['density']:.3f}, Connected: {info['is_connected']}")

🧠 Memory-Enhanced Graphs

Memory graphs track connections over time, allowing analysis of temporal patterns:

# Initialize memory manager
grapher.init_memory_manager(max_memory_size=50, track_edge_ages=True)

# Simulate evolution over time
for iteration in range(100):
    # Update positions (e.g., particle movement)
    data[:, 1:3] += np.random.normal(0, 2, (len(data), 2))
    
    # Create current graph and update memory
    current_graph = grapher.make_proximity(data, proximity_thresh=60.0)
    grapher.update_memory_with_graph(current_graph)
    
    # Create memory-enhanced graph (current + historical connections)
    memory_graph = grapher.make_memory_graph(data)
    
    # Visualize with age-based coloring
    if iteration % 10 == 0:
        memory_image = grapher.draw_memory_graph(
            memory_graph, 
            use_age_colors=True,  # Older connections fade out
            alpha_range=(0.3, 1.0)
        )
        grapher.save_graph(memory_image, f"memory_frame_{iteration:03d}.jpg")

# Get memory statistics
stats = grapher.get_memory_stats()
print(f"Memory contains {stats['total_connections']} historical connections")
print(f"Average edge age: {stats['edge_age_stats']['avg_age']:.1f} iterations")

📊 Graph Types Comparison

Graph Type	Connectivity	Edge Count	Use Case	Memory Compatible
Proximity	Variable	~distance²	Local neighborhoods	✅
Delaunay	Always	~3n	Natural triangulation	✅
K-NN	Variable	k×n	Fixed degree networks	✅
MST	Always	n-1	Minimal connectivity	✅
Gabriel	Variable	Subset of Delaunay	Geometric proximity	✅
Memory	Variable	Historical	Temporal analysis	-

🎮 Interactive Demo

Experience real-time graph evolution with the interactive Brownian motion simulator:

# Basic proximity graph simulation
python examples/improved_brownian.py 1

# Delaunay triangulation with memory tracking
python examples/improved_brownian.py 2 --memory

# Minimum spanning tree evolution
python examples/improved_brownian.py 4 --memory --particles 100

# Compare all graph types side-by-side
python examples/improved_brownian.py 5 --memory

# Interactive controls:
# ESC - Exit, SPACE - Pause, R - Reset, M - Toggle memory
# 1-5 - Switch graph types, +/- - Adjust memory size

⚙️ Configuration

Graphizy uses dataclasses for type-safe, runtime-configurable parameters:

from graphizy import GraphizyConfig

# Create and customize configuration
config = GraphizyConfig()

# Drawing configuration
config.drawing.line_color = (255, 0, 0)  # Red lines (B, G, R)
config.drawing.point_color = (0, 255, 255)  # Yellow points  
config.drawing.line_thickness = 3
config.drawing.point_radius = 12

# Graph configuration
config.graph.dimension = (1200, 800)
config.graph.proximity_threshold = 75.0
config.graph.distance_metric = "euclidean"  # or "manhattan", "chebyshev"

# Memory configuration
config.memory.max_memory_size = 100
config.memory.auto_update_from_proximity = True

# Create grapher with custom config
grapher = Graphing(config=config)

# Runtime configuration updates
grapher.update_config(
    drawing={"line_thickness": 5},
    graph={"proximity_threshold": 100.0}
)

🔬 Advanced Analysis

Graph Metrics and Centrality

# Basic graph properties
info = grapher.get_graph_info(graph)
print(f"Density: {info['density']:.3f}")
print(f"Average path length: {info['average_path_length']:.2f}")
print(f"Clustering coefficient: {info['transitivity']:.3f}")

# Node centrality measures
degree_centrality = grapher.call_method(graph, 'degree')
betweenness = grapher.call_method(graph, 'betweenness')
closeness = grapher.call_method(graph, 'closeness')

# Find most central nodes
central_nodes = sorted(betweenness.items(), key=lambda x: x[1], reverse=True)[:5]
print(f"Top 5 central nodes: {central_nodes}")

# Direct igraph access for advanced analysis
components = grapher.call_method_raw(graph, 'connected_components')
diameter = grapher.call_method_raw(graph, 'diameter')

Custom Graph Types

# Create custom connection function
def create_distance_band_graph(positions, inner_radius=30, outer_radius=80):
    """Connect points within a distance band (ring)"""
    from scipy.spatial.distance import pdist, squareform
    
    graph = grapher.make_proximity(positions, proximity_thresh=float('inf'))
    graph.delete_edges(graph.es)  # Start empty
    
    distances = squareform(pdist(positions[:, 1:3]))
    edges = []
    
    for i in range(len(positions)):
        for j in range(i+1, len(positions)):
            dist = distances[i, j]
            if inner_radius <= dist <= outer_radius:
                edges.append((i, j))
    
    if edges:
        graph.add_edges(edges)
    return graph

# Use with memory system
custom_graph = create_distance_band_graph(data, 40, 100)
grapher.update_memory_with_graph(custom_graph)

📚 API Reference

Main Classes

• Graphing: Primary interface for graph creation and analysis
• GraphizyConfig: Type-safe configuration management
• MemoryManager: Historical connection tracking
• DataInterface: Flexible data format handling

Graph Creation Methods

• make_delaunay(data): Delaunay triangulation
• make_proximity(data, proximity_thresh, metric): Distance-based connections
• make_knn(data, k): K-nearest neighbors (requires scipy)
• make_mst(data, metric): Minimum spanning tree
• make_gabriel(data): Gabriel graph
• make_memory_graph(data): Memory-enhanced graph

Memory Management

• init_memory_manager(max_size, max_iterations, track_ages): Initialize memory
• update_memory_with_graph(graph): Add graph connections to memory
• update_memory_with_proximity(data, threshold): Add proximity connections
• get_memory_stats(): Memory usage statistics

Visualization

• draw_graph(graph, radius, thickness): Standard graph drawing
• draw_memory_graph(graph, use_age_colors, alpha_range): Memory visualization
• show_graph(image, title): Interactive display
• save_graph(image, filename): Save to file

🧪 Examples

Batch Analysis

# Analyze multiple datasets
results = []
for size in [50, 100, 200, 500]:
    positions = generate_positions(800, 800, size)
    data = np.column_stack((np.arange(size), positions))
    
    # Compare graph types
    for graph_type, create_func in [
        ('delaunay', lambda d: grapher.make_delaunay(d)),
        ('proximity', lambda d: grapher.make_proximity(d, 60)),
        ('mst', lambda d: grapher.make_mst(d)),
        ('gabriel', lambda d: grapher.make_gabriel(d))
    ]:
        graph = create_func(data)
        info = grapher.get_graph_info(graph)
        results.append({
            'size': size,
            'type': graph_type,
            'density': info['density'],
            'avg_path_length': info['average_path_length']
        })

# Analyze results
import pandas as pd
df = pd.DataFrame(results)
print(df.groupby('type')['density'].mean())

Time Series Analysis

# Track graph evolution over time
time_series = []
grapher.init_memory_manager(max_memory_size=200)

for t in range(500):
    # Simulate system evolution  
    data[:, 1:3] += np.random.normal(0, 1, (len(data), 2))
    
    # Create snapshot
    current_graph = grapher.make_delaunay(data)
    grapher.update_memory_with_graph(current_graph)
    
    # Record metrics
    info = grapher.get_graph_info(current_graph)
    memory_stats = grapher.get_memory_stats()
    
    time_series.append({
        'time': t,
        'current_edges': info['edge_count'],
        'memory_edges': memory_stats['total_connections'],
        'clustering': info['transitivity']
    })

# Visualize time series
import matplotlib.pyplot as plt
ts_df = pd.DataFrame(time_series)
ts_df.plot(x='time', y=['current_edges', 'memory_edges'])
plt.title('Graph Evolution Over Time')
plt.show()

🔧 Development

Requirements

• Python >= 3.8
• NumPy >= 1.20.0
• OpenCV >= 4.5.0
• python-igraph >= 0.9.0
• SciPy >= 1.7.0 (for KNN and MST)

Running Tests

# Install development dependencies
pip install pytest pytest-cov black flake8

# Run tests with coverage
pytest tests/ --cov=graphizy --cov-report=html

# Test specific functionality
python test_mst.py          # Test MST functionality
python test_fixes.py        # Test configuration fixes

Code Quality

# Format code
black src/

# Lint code  
flake8 src/

# Type checking (if mypy installed)
mypy src/graphizy/

📄 License

GPL-2.0-or-later License - see LICENSE file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Ensure all tests pass (pytest tests/)
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

👨‍💻 Author

Charles Fosseprez
📧 Email: [e-mail]
🐙 GitHub: @cfosseprez

📈 Changelog

v0.1.4 (Current)

• ✨ Added Minimum Spanning Tree (MST) graph type
• ✨ Added K-Nearest Neighbors (KNN) graph type
• 🧠 Enhanced memory system with age-based visualization
• 🎮 Interactive Brownian motion simulator
• 🐛 Fixed configuration initialization issues
• 📚 Comprehensive documentation improvements
• ✅ Added MST and memory functionality tests

v0.1.0

• 🎉 Initial release
• 🔺 Delaunay triangulation support
• 📡 Proximity graph creation
• ⚙️ Configurable drawing parameters
• 🖥️ Command line interface
• ✅ Comprehensive test suite
• 🛡️ Error handling and validation

---

Built with ❤️ for computational geometry and network analysis