Quick Start Guide

This guide will get you up and running with Graphizy in just a few minutes. You’ll learn the basic concepts and see how to create your first spatial networks.

Installation

Install Graphizy using pip:

pip install graphizy

For development or the latest features:

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

Basic Concepts

What is Graphizy?

Graphizy creates networks (graphs) from spatial coordinate data. Think of it as connecting dots based on their positions in space, with different connection rules creating different types of networks.

Key Components:

  • Graphing: The main class that creates and analyzes networks

  • Data Format: Your spatial coordinates in a simple format

  • Graph Types: Different ways to connect points (proximity, triangulation, etc.)

  • Analysis Tools: Advanced analyzers for research applications

Your First Graph

Let’s create a simple network from random points:

from graphizy import Graphing, generate_and_format_positions

# Step 1: Generate some random points
data = generate_and_format_positions(
    size_x=400,      # Canvas width
    size_y=300,      # Canvas height
    num_particles=30 # Number of points
)

# Step 2: Create a Graphing object
grapher = Graphing(dimension=(400, 300))

# Step 3: Create a proximity network
# Points within 60 units of each other get connected
graph = grapher.make_graph("proximity", data, proximity_thresh=60.0)

# Step 4: Visualize the result
image = grapher.draw_graph(graph)
grapher.show_graph(image, "My First Network")

That’s it! You’ve created your first spatial network.

Understanding the Data Format

Graphizy expects data in a simple format: each row represents one point with an ID and coordinates.

import numpy as np

# Manual data creation
data = np.array([
    [0, 100, 150],  # Point 0 at position (100, 150)
    [1, 200, 200],  # Point 1 at position (200, 200)
    [2, 150, 100],  # Point 2 at position (150, 100)
    # ... more points
])

# Or use the helper function
data = generate_and_format_positions(400, 300, 30)

Data Requirements: - Column 0: Point ID (unique identifier) - Column 1: X coordinate - Column 2: Y coordinate

Different Graph Types

Graphizy offers several ways to connect your points:

Proximity Graph - Connect nearby points:

# Connect points within 50 units of each other
proximity_graph = grapher.make_graph("proximity", data, proximity_thresh=50.0)

Delaunay Triangulation - Optimal triangular mesh:

# Create triangular mesh (no overlapping triangles)
delaunay_graph = grapher.make_graph("delaunay", data)

K-Nearest Neighbors - Connect to closest neighbors:

# Each point connects to its 4 closest neighbors
knn_graph = grapher.make_graph("knn", data, k=4)

Minimum Spanning Tree - Minimal connected network:

# Minimum edges needed to connect all points
mst_graph = grapher.make_graph("mst", data)

Gabriel Graph - Geometric proximity network:

# Special geometric connectivity rules
gabriel_graph = grapher.make_graph("gabriel", data)

Analyzing Your Networks

Once you have a graph, you can analyze its properties:

# Get comprehensive analysis
result = grapher.get_graph_info(graph)

# Basic properties
print(f"Number of points: {result.vertex_count}")
print(f"Number of connections: {result.edge_count}")
print(f"Network density: {result.density:.3f}")
print(f"Is connected: {result.is_connected}")

# Advanced properties
if result.transitivity is not None:
    print(f"Clustering coefficient: {result.transitivity:.3f}")

if result.diameter is not None:
    print(f"Network diameter: {result.diameter}")

Quick Summary Report:

# Get a formatted summary
print(result.summary())

Advanced Analysis Tools (New!)

Graphizy now includes powerful research-grade analysis tools:

Percolation Analysis - Find critical thresholds:

# Test different connection distances
ranges = [20, 30, 40, 50, 60, 70]

# Analyze percolation behavior
percolation_result = result.percolation_analyzer.analyze_percolation_threshold(
    data, ranges
)

print(f"Critical threshold: {percolation_result.critical_range}")
print(f"Largest cluster: {max(percolation_result.largest_cluster_sizes)}")

Social Network Analysis - Identify roles:

# Identify social roles in the network
social_roles = result.social_analyzer.identify_social_roles(graph)

# Find bridges (connectors between groups)
bridges = [node_id for node_id, role in social_roles.items()
          if role.is_bridge()]

# Find hubs (highly connected nodes)
hubs = [node_id for node_id, role in social_roles.items()
       if role.is_hub()]

print(f"Network bridges: {bridges}")
print(f"Network hubs: {hubs}")

Accessibility Analysis - Study spatial coverage:

# For spatial planning applications
population_points = data  # Your population data
service_points = service_data  # Your service locations

accessibility_result = result.accessibility_analyzer.analyze_service_accessibility(
    population_points, service_points,
    service_type="hospital",
    service_distance=500.0  # 500m walking distance
)

print(f"Coverage: {accessibility_result.get_coverage_percentage():.1f}%")
print(f"Equity score: {accessibility_result.get_equity_score():.3f}")

Memory System for Temporal Analysis

Track how networks change over time:

# Initialize memory system
grapher.init_memory_manager(
    max_memory_size=50,    # Remember last 50 connections
    track_edge_ages=True   # Track how long connections last
)

# Simulate evolution over time
for timestep in range(20):
    # Update positions (your simulation)
    data = update_positions(data, timestep)

    # Create current network
    current_graph = grapher.make_graph("proximity", data, proximity_thresh=60.0)

    # Update memory with current connections
    grapher.update_memory_with_graph(current_graph)

    # Visualize memory-enhanced network
    if timestep % 5 == 0:
        memory_graph = grapher.make_memory_graph(data)
        memory_image = grapher.draw_memory_graph(
            memory_graph,
            use_age_colors=True,      # Color by connection age
            alpha_range=(0.3, 1.0)   # Fade old connections
        )
        grapher.save_graph(memory_image, f"evolution_{timestep:02d}.png")

Customizing Visualization

Make your networks look exactly how you want:

# Update drawing style
grapher.update_config(drawing={
    "point_color": (255, 100, 100),  # Red points (B, G, R format)
    "line_color": (100, 255, 100),   # Green lines
    "point_radius": 8,               # Larger points
    "line_thickness": 2              # Thicker lines
})

# Draw with custom style
styled_image = grapher.draw_graph(graph)
grapher.save_graph(styled_image, "styled_network.png")

Saving and Loading

Save your work for later:

# Save graph visualization
grapher.save_graph(image, "my_network.png")

# Save analysis results
import json

analysis_data = {
    'vertex_count': result.vertex_count,
    'edge_count': result.edge_count,
    'density': result.density,
    'is_connected': result.is_connected
}

with open('analysis_results.json', 'w') as f:
    json.dump(analysis_data, f, indent=2)

Export to Other Tools:

# Export to NetworkX for advanced analysis
try:
    import networkx as nx
    nx_graph = grapher.to_networkx(graph)

    # Now use NetworkX methods
    communities = nx.community.greedy_modularity_communities(nx_graph)
    print(f"Found {len(communities)} communities")
except ImportError:
    print("NetworkX not available")

Common Patterns

Compare Multiple Graph Types:

# Create different graph types from same data
graph_types = {
    'Proximity': grapher.make_graph("proximity", data, proximity_thresh=50.0),
    'Delaunay': grapher.make_graph("delaunay", data),
    'MST': grapher.make_graph("mst", data),
    'KNN': grapher.make_graph("knn", data, k=4)
}

# Compare properties
print(f"{'Type':<12} {'Edges':<8} {'Density':<10} {'Connected':<10}")
print("-" * 45)

for name, graph in graph_types.items():
    info = grapher.get_graph_info(graph)
    print(f"{name:<12} {info.edge_count:<8} {info.density:<10.3f} {info.is_connected}")

Batch Processing:

# Process multiple datasets
datasets = [
    generate_and_format_positions(400, 300, 20),
    generate_and_format_positions(400, 300, 50),
    generate_and_format_positions(400, 300, 100)
]

results = []
for i, data in enumerate(datasets):
    graph = grapher.make_graph("proximity", data, proximity_thresh=60.0)
    info = grapher.get_graph_info(graph)

    results.append({
        'dataset': i,
        'points': info.vertex_count,
        'connections': info.edge_count,
        'density': info.density
    })

    # Save visualization
    image = grapher.draw_graph(graph)
    grapher.save_graph(image, f"dataset_{i}_network.png")

What’s Next?

Now that you know the basics, explore these advanced topics:

  1. Memory Systems: Track temporal evolution in dynamic networks

  2. Weight Computation: Add sophisticated edge weights and attributes

  3. Plugin System: Create custom graph types for your specific needs

  4. Research Applications: Use the specialized analysis tools for your domain

  5. Performance Optimization: Handle large datasets efficiently

Recommended Learning Path:

  1. Start Here: Complete this quickstart guide

  2. Basic Usage: Learn all graph types and analysis methods

  3. Advanced Analysis: Explore the new research-grade analyzers

  4. Memory Systems: Add temporal analysis to your networks

  5. Research Applications: Check out domain-specific tutorials

  6. Custom Development: Create plugins and custom analysis methods

Get Help:

  • Documentation: Comprehensive guides and API reference

  • Examples: Working code for common use cases

  • Tutorials: Research-grade applications in multiple domains

  • GitHub Issues: Report bugs or request features

Example Research Tutorials:

  • Particle Physics: Percolation analysis and phase transitions

  • Animal Behavior: Social network dynamics and role identification

  • Urban Planning: Accessibility analysis and spatial equity

You’re now ready to create sophisticated spatial networks and perform advanced analysis with Graphizy!