Community evolution visualization for student social networks
Built with Java and JUNG (Java Universal Network/Graph Framework)
GraphVisual is a desktop application for studying community evolution in student populations using Bluetooth proximity data. It processes meeting records from a PostgreSQL database, classifies social relationships (friends, classmates, strangers, study groups, familiar strangers), and renders interactive graph visualizations with timeline playback.
The tool was developed for research on social network analysis — specifically understanding how communities form, dissolve, and evolve over time in university settings.
- Interactive graph visualization — Drag, zoom, rotate nodes with JUNG's built-in graph mouse
- Timeline playback — Animate community graphs across 92 days (March–May 2011) with play/pause/stop controls
- 5 relationship categories — Friends (green), Classmates (blue), Familiar Strangers (gray), Strangers (red), Study Groups (orange)
- Adjustable thresholds — Tune meeting duration and frequency thresholds per relationship type in real-time
- Cluster-based layout — Nodes auto-grouped into a 3×3 grid by relationship type, with randomized positioning
- Edge weighting — Line thickness reflects interaction frequency × duration
- New member highlighting — Nodes appearing for the first time are drawn larger
- Notes panel — Annotate each timestamp during analysis
- Graph export — Save visualizations as PNG images, edge lists, and JSON (D3.js/vis.js/Cytoscape.js compatible)
- Network statistics panel — Real-time metrics including node/edge counts, per-category breakdowns, graph density, average/max degree, average edge weight, isolated node count, and top-3 hub nodes
- Centrality analysis — Compute degree, betweenness (Brandes' algorithm), and closeness centrality for all nodes. Interactive panel with metric sorting, top-10 ranking with medals, network topology classification, and per-metric averages/maximums
- Small-world analysis — Test whether a graph exhibits Watts-Strogatz small-world properties. Computes local/global clustering coefficients, average path length, sigma (σ) and omega (ω) coefficients, random/lattice baselines, and classifies networks as Small-World, Random-Like, Lattice-Like, or Disconnected
- Subgraph extraction — Extract focused subgraphs using a fluent builder API. Filter by edge type, weight range, degree range, k-hop neighborhood, node whitelist, or time window. Export results as CSV edge lists with retention statistics and edge type breakdowns
- Community detection — Interactive browser tool with 4 algorithms (Louvain modularity, Label Propagation, Girvan-Newman edge betweenness, Spectral Bisection). 6 preset graphs (Karate Club, Barbell, Caveman, SBM, Ring of Cliques), force-directed layout with adjustable parameters, color-coded communities, modularity scoring, per-community density stats, drag-to-move nodes, pan/zoom, JSON/SVG export
- Network flow visualizer — Interactive browser tool for max-flow / min-cut visualization with Edmonds-Karp and Ford-Fulkerson algorithms. Step-by-step animation, 5 preset networks (simple, diamond, bipartite matching, complex, bottleneck), canvas graph editor, min-cut highlighting, JSON/SVG export. Java
NetworkFlowExporterclass for programmatic flow computation and HTML export - Random graph generator — Interactive browser tool for generating graphs using 7 classic models (Erdős–Rényi, Barabási–Albert, Watts-Strogatz, Random Geometric, Complete, Star, Ring). Force-directed layout, degree/community coloring, drag-and-zoom, degree distribution chart, real-time stats (density, clustering, diameter, components), JSON/PNG export
- Network resilience analyzer — Interactive browser tool for simulating targeted and random attacks on networks. 4 attack strategies (highest-degree, highest-betweenness, random, cascading with recalculation), 6 preset graphs (Barabási-Albert, Erdős-Rényi, Watts-Strogatz, Star, Grid, Karate Club), real-time robustness curve plotting, R-index computation, strategy comparison overlay, step-through animation, attack log, force-directed layout with drag interaction
GraphVisual consists of 192 source classes (176 in gvisual/ + 7 in app/; ~83,700 lines of production code, ~133,000+ total with tests), 58 graph analyzers (plus engines, advisors, exporters, and panel controllers), and a Bluetooth-to-graph data pipeline. See ARCHITECTURE.md, ALGORITHMS.md, and TESTING.md for full details including the analyzer reference table, design patterns, dependency map, and testing guide.
Gvisual/src/
├── gvisual/ # 169 classes — GUI, edge model, 58 analyzers, engines, exporters, controllers, utilities
│ ├── Main.java # Swing GUI — graph panel, timeline, controls
│ ├── edge.java # Edge model (type, vertices, weight, label)
│ ├── EdgeType.java # Enum — relationship categories, colors, defaults
│ ├── GraphStats.java # Network metrics (density, degree, hubs)
│ ├── GraphMLExporter.java # GraphML XML export
│ ├── JsonGraphExporter.java # JSON export (D3.js/vis.js/Cytoscape.js compatible)
│ ├── GraphGenerator.java # 10 synthetic graph topologies
│ ├── GraphUtils.java # BFS, connected components, utility methods
│ ├── GraphPartitioner.java # Spectral/Kernighan-Lin partitioning
│ ├── ForceDirectedLayout.java # Force-directed graph layout (Barnes-Hut)
│ ├── AnalysisTask.java # Async analysis with timeout/cancellation
│ ├── AnalysisResult.java # Analysis result container
│ │
│ │── # ─── Structural Analyzers ──────────────────
│ ├── ArticulationPointAnalyzer.java # Cut vertices/bridges (Tarjan's)
│ ├── BipartiteAnalyzer.java # Bipartiteness testing + 2-coloring
│ ├── ChordalGraphAnalyzer.java # Chordal graph recognition (PEO)
│ ├── CliqueAnalyzer.java # Maximal cliques (Bron-Kerbosch)
│ ├── CycleAnalyzer.java # Cycle detection and enumeration
│ ├── EulerianPathAnalyzer.java # Euler path/circuit (Hierholzer's)
│ ├── GraphComplementAnalyzer.java # Graph complement computation
│ ├── GraphIsomorphismAnalyzer.java # Graph isomorphism testing
│ ├── GraphIsomorphismChecker.java # VF2-inspired isomorphism (backtracking)
│ ├── GraphMinorAnalyzer.java # Graph minor detection
│ ├── GraphRegularityAnalyzer.java # Regularity testing
│ ├── GraphSymmetryAnalyzer.java # Automorphism & symmetry analysis
│ ├── LineGraphAnalyzer.java # Line graph construction + analysis
│ ├── PerfectGraphAnalyzer.java # Perfect graph recognition
│ ├── PlanarGraphAnalyzer.java # Planarity testing
│ ├── TreeAnalyzer.java # Tree properties, LCA, diameter
│ ├── TopologicalSortAnalyzer.java # Topo sort + cycle detection
│ ├── StronglyConnectedComponentsAnalyzer.java # SCC (Tarjan/Kosaraju)
│ │
│ │── # ─── Centrality & Ranking ──────────────────
│ ├── NodeCentralityAnalyzer.java # Degree/betweenness/closeness
│ ├── EdgeBetweennessAnalyzer.java # Edge betweenness centrality
│ ├── PageRankAnalyzer.java # PageRank (power iteration)
│ ├── DegreeDistributionAnalyzer.java # Degree stats + power-law fitting
│ ├── RichClubAnalyzer.java # Rich-club coefficient
│ │
│ │── # ─── Community & Clustering ────────────────
│ ├── CommunityDetector.java # Connected component communities
│ ├── LouvainCommunityDetector.java # Louvain modularity optimization
│ ├── CliqueCoverAnalyzer.java # Clique cover computation
│ ├── GraphClusterQualityAnalyzer.java # Cluster quality metrics
│ ├── KTrussAnalyzer.java # K-truss decomposition
│ ├── MotifAnalyzer.java # Network motif detection
│ ├── NodeSimilarityAnalyzer.java # Jaccard/cosine node similarity
│ ├── SignedGraphAnalyzer.java # Signed graph balance theory
│ ├── StructuralHoleAnalyzer.java # Burt's structural holes
│ │
│ │── # ─── Optimization & NP-hard ────────────────
│ ├── BandwidthMinimizer.java # Graph bandwidth minimization
│ ├── ChromaticPolynomialCalculator.java # Chromatic polynomial (deletion-contraction)
│ ├── DominatingSetAnalyzer.java # Minimum dominating set
│ ├── FeedbackVertexSetAnalyzer.java # Feedback vertex set
│ ├── GraphColoringAnalyzer.java # Welsh-Powell vertex coloring
│ ├── HamiltonianAnalyzer.java # Hamiltonian path/cycle
│ ├── IndependentSetAnalyzer.java # Maximum independent set
│ ├── MaxCutAnalyzer.java # Maximum cut problem
│ ├── MetricDimensionAnalyzer.java # Metric dimension (resolving sets)
│ ├── SteinerTreeAnalyzer.java # Steiner tree approximation
│ ├── TreewidthAnalyzer.java # Treewidth estimation
│ ├── VertexConnectivityAnalyzer.java # Vertex connectivity
│ ├── VertexCoverAnalyzer.java # Minimum vertex cover
│ │
│ │── # ─── Network Analysis ──────────────────────
│ ├── GraphAnomalyDetector.java # Network anomaly detection
│ ├── GraphNeighborhoodAnalyzer.java # k-hop neighborhood analysis
│ ├── LinkPredictionAnalyzer.java # Edge prediction metrics
│ ├── NetworkFlowAnalyzer.java # Max-flow/min-cut (Ford-Fulkerson)
│ ├── GraphResilienceAnalyzer.java # Attack/failure resilience
│ ├── GraphSparsificationAnalyzer.java # Graph sparsification algorithms
│ ├── InfluenceSpreadSimulator.java # IC/LT influence models
│ ├── RandomWalkAnalyzer.java # Random walks, hitting/cover times
│ ├── SmallWorldAnalyzer.java # Small-world property testing (σ, ω)
│ ├── TemporalGraph.java # Temporal graph evolution analysis
│ │
│ │── # ─── Metrics & Comparison ──────────────────
│ ├── AdjacencyMatrixHeatmap.java # Adjacency matrix visualization
│ ├── GraphEntropyAnalyzer.java # 9 entropy measures
│ ├── GraphSimilarityAnalyzer.java # Entropy-based graph comparison
│ ├── GraphDiffAnalyzer.java # Structural diff between graphs
│ ├── GraphDrawingQualityAnalyzer.java # Layout quality metrics
│ ├── EdgePersistenceAnalyzer.java # Edge stability over time
│ ├── GrowthRateAnalyzer.java # Network growth modeling
│ ├── LaplacianBuilder.java # Laplacian matrix construction
│ ├── SpectralAnalyzer.java # Eigenvalue spectral analysis
│ ├── GraphSpectrumAnalyzer.java # Full spectrum analysis
│ ├── TournamentAnalyzer.java # Tournament graph analysis
│ │
│ │── # ─── Algorithms ────────────────────────────
│ ├── KCoreDecomposition.java # K-core peeling
│ ├── MinimumSpanningTree.java # Kruskal's MST
│ ├── ShortestPathFinder.java # BFS + weighted Dijkstra
│ ├── GraphRenderers.java # Custom graph rendering
│ └── GraphDiameterAnalyzer.java # Diameter, radius, eccentricity
└── app/ # Data pipeline — Bluetooth → meetings → edge files
├── Network.java, Util.java, findMeetings.java, addLocation.java, matchImei.java
133 test classes with 4,600+ tests cover all analyzers and utilities.
- Java JDK 8 or later
- PostgreSQL database with the expected schema (
meeting,event_3,device_1,deviceIDtables) - Apache Ant (NetBeans project build system)
git clone https://github.com/sauravbhattacharya001/GraphVisual.git
cd GraphVisualGraphVisual reads credentials from environment variables (no hardcoded secrets):
export DB_HOST=localhost # PostgreSQL host (default: localhost)
export DB_USER=your_user # Required
export DB_PASS=your_pass # Requiredcd Gvisual
ant buildOr compile manually:
cd Gvisual
mkdir -p build/classes
find src -name '*.java' > sources.txt
javac -cp "$(find lib -name '*.jar' | tr '\n' ':')" -d build/classes @sources.txtExecute these in order to populate the meeting database:
# Step 1: Match device nodes to IMEIs
java -cp "build/classes:lib/*" app.matchImei
# Step 2: Extract meetings from Bluetooth events
java -cp "build/classes:lib/*" app.findMeetings
# Step 3: Classify meeting locations
java -cp "build/classes:lib/*" app.addLocationjava -cp "build/classes:lib/*" gvisual.Main| Component | Description |
|---|---|
| Image Panel | Main graph canvas powered by JUNG. Supports drag, zoom, and rotation. |
| Timeline Panel | Slider (days 1–92) with play/pause/stop and skip controls. Speed adjustable. |
| Toolbar | Left-side tools for interaction mode (transform vs. pick), image/edge-list export. |
| Category Panel | Toggle visibility of each relationship type. Expand to adjust duration/frequency thresholds. |
| Notes Pane | Free-text area for annotating the currently viewed graph timestamp. |
| Statistics Panel | Live network metrics — node/edge counts, density, degree stats, and hub identification. |
| Centrality Panel | Compute and rank nodes by degree, betweenness, and closeness centrality with sortable metric selector. |
| Type | Color | Location | Duration Threshold | Meeting Count |
|---|---|---|---|---|
| Friends | 🟢 Green | Public areas | > 10 min | ≥ 2/day |
| Classmates | 🔵 Blue | Classrooms | > 30 min | ≥ 1/day |
| Study Groups | 🟠 Orange | Classrooms | > 20 min | ≤ 1/day |
| Familiar Strangers | ⚪ Gray | Public/paths | < 2 min | > 1/day |
| Strangers | 🔴 Red | Public/paths | < 2 min | < 2/day |
All thresholds are adjustable at runtime via the Category Panel sliders.
| Technology | Purpose |
|---|---|
| Java 8+ | Application language |
| JUNG 2.0.1 | Graph data structures and visualization |
| Swing | Desktop GUI framework |
| PostgreSQL | Meeting and Bluetooth event storage |
| Apache Ant | Build system (NetBeans) |
| Commons IO | File I/O utilities |
| Java3D | 3D graph rendering support |
| JUnit 4 | Unit testing framework |
| GitHub Actions | CI/CD (build + test on JDK 11/17) |
| CodeQL | Automated security scanning |
The test suite includes 133 test classes with 4,600+ tests covering analyzers, exporters, layouts, and utilities.
# Run all tests
mvn test
# Run a single test class
mvn test -Dtest=BipartiteAnalyzerTest
# Run a specific method
mvn test -Dtest=BipartiteAnalyzerTest#testMaximumMatchingCompleteBipartiteSee TESTING.md for the full testing guide: conventions, coverage gaps, and how to write new tests.
Multiple ways to get GraphVisual running — pick your preferred method.
Linux / macOS:
curl -fsSL https://raw.githubusercontent.com/sauravbhattacharya001/GraphVisual/master/install.sh | bashWindows (PowerShell):
irm https://raw.githubusercontent.com/sauravbhattacharya001/GraphVisual/master/install.ps1 | iexBoth installers download the latest fat JAR, create a graphvisual launcher, and add it to your PATH. Requires Java 11+.
Install a specific version:
# Linux/macOS
curl -fsSL .../install.sh | bash -s -- --version v2.62.0
# Windows
$env:GRAPHVISUAL_VERSION = "v2.62.0"; irm .../install.ps1 | iex# Download the latest fat JAR
gh release download --repo sauravbhattacharya001/GraphVisual --pattern "*-all.jar"
java -jar graphvisual-*-all.jarGraphVisual is published to GitHub Packages.
- Configure GitHub Packages in your
~/.m2/settings.xml:
<servers>
<server>
<id>github</id>
<username>YOUR_GITHUB_USERNAME</username>
<password>YOUR_GITHUB_TOKEN</password>
</server>
</servers>- Add the repository and dependency to your
pom.xml:
<repositories>
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/sauravbhattacharya001/GraphVisual</url>
</repository>
</repositories>
<dependency>
<groupId>com.github.sauravbhattacharya001</groupId>
<artifactId>graphvisual</artifactId>
<version>2.62.0</version>
</dependency>Each release includes a standalone graphvisual-*-all.jar with all dependencies bundled:
java -jar graphvisual-2.62.0-all.jargit clone https://github.com/sauravbhattacharya001/GraphVisual.git
cd GraphVisual
# Install vendored local JARs first
mvn initialize -P install-local-deps
# Build the project
mvn package -B
# Run
java -jar target/graphvisual-*-all.jardocker build -t graphvisual .# Allow X11 forwarding
xhost +local:docker
docker run --rm \
-e DISPLAY=$DISPLAY \
-v /tmp/.X11-unix:/tmp/.X11-unix \
graphvisualdocker pull ghcr.io/sauravbhattacharya001/graphvisual:latestNote: The Dockerfile builds a fat JAR with all dependencies, compiles source, runs tests during build, and packages a minimal JRE-based runtime image (~300MB). X11 libraries are included for optional GUI support via display forwarding.
You can explore GraphVisual's 43 analyzers using the built-in synthetic graph generators without any database setup:
import gvisual.GraphGenerator;
// Generate a 100-node scale-free network (Barabási-Albert)
var graph = GraphGenerator.barabasiAlbert(100, 3);
// Or try other topologies:
// GraphGenerator.erdosRenyi(50, 0.15)
// GraphGenerator.wattsStrogatz(60, 6, 0.3)
// GraphGenerator.complete(20)
// GraphGenerator.star(30)
// GraphGenerator.grid(8, 8)Then run any analyzer:
import gvisual.*;
var centrality = new NodeCentralityAnalyzer();
var result = centrality.analyze(graph);
System.out.println(result);
var smallWorld = new SmallWorldAnalyzer();
System.out.println(smallWorld.analyze(graph));| Category | Count | Highlights |
|---|---|---|
| Structural | 12 | Cliques, cycles, planarity, isomorphism, articulation points |
| Centrality & Ranking | 3 | PageRank, degree/betweenness/closeness, degree distribution |
| Community & Clustering | 4 | Community detection, motifs, structural holes, signed graphs |
| NP-hard Optimization | 11 | Graph coloring, Hamiltonian paths, vertex cover, max cut |
| Network Analysis | 8 | Max-flow, influence spread, random walks, resilience testing |
| Metrics & Comparison | 8 | Spectral analysis, entropy, graph diff, edge persistence |
See ALGORITHMS.md for the complete reference with time complexities and algorithm details.
Given the original graph and an ordered attack trace (the nodes that were removed, in chronological order), GraphAdversaryForecaster replays the trace step by step, infers which strategy best explains the observed removal order (RANDOM, DEGREE_TARGETING, BETWEENNESS_TARGETING, BRIDGE_TARGETING, COMMUNITY_CUT, PERIPHERAL), forecasts the top-K next targets with softmax probabilities, and emits prioritized defenses (HARDEN, ADD_REDUNDANT_EDGE with a concrete suggested edge, MONITOR, DECOY) tagged P0/P1/P2 by expected impact on the largest connected component.
GraphAdversaryForecaster fc =
new GraphAdversaryForecaster(originalGraph, attackTrace).withTopK(5);
GraphAdversaryForecaster.Forecast f = fc.analyze();
System.out.println(fc.toMarkdown(f)); // or toText / toJsonThis project was built to study community evolution in student social networks using Bluetooth proximity sensing. Key research questions:
- How do social communities form and evolve over a semester?
- What distinguishes friends from familiar strangers based on meeting patterns?
- How do physical spaces (classrooms vs. public areas) shape community structure?
The visualization tool enables researchers to explore these questions interactively by adjusting relationship parameters and observing how graph structures change over time.
Contributions are welcome! See CONTRIBUTING.md for full details on:
- Development setup and building
- Code style and architecture overview
- Testing guidelines
- Pull request process and commit conventions
Quick start: fork → branch → make changes with tests → submit PR.