Scholar Graph Kit: Tutorial

This tutorial demonstrates how to visualize citation networks using scholar-graph-kit.

Command Line Interface

You can generate a citation map directly from one or more seed DOIs:

scholar-bib build --doi "10.1038/nature14539" --output graph.html

Or you can pipe the output from scholar-search-kit:

scholar-bib build --input search_results.json --direction both

Options

• --doi, -d: Provide specific DOIs to seed the graph. Can be used multiple times.
• --input, -i: Pass a JSON file generated by scholar-search-kit to automatically map an entire systematic review.
• --direction: How to expand the network (forward for papers citing the seed, backward for papers the seed cites, or both).
• --output, -o: The name of the HTML file to save the visualization to.

Python API

You can also orchestrate the graph generation programmatically:

from scholar_graph.builder import GraphBuilder
from scholar_graph.analyzer import NetworkAnalyzer
from scholar_graph.visualizer import GraphVisualizer
from pathlib import Path

# 1. Fetch network
builder = GraphBuilder()
graph_data = builder.build_graph(["10.1038/nature14539"], direction="both")

# 2. Compute PageRank
analyzer = NetworkAnalyzer(graph_data)

# 3. Export to HTML
visualizer = GraphVisualizer(analyzer)
visualizer.export_html(Path("citation_map.html"))

Scholar Graph Kit: API Reference

This document provides the API contracts for the core components of scholar-graph-kit.

GraphBuilder

Fetches citation data from OpenAlex and constructs a GraphData object.

from scholar_graph.builder import GraphBuilder

builder = GraphBuilder(provider="openalex")

# Expand forward (citations), backward (references), or both
graph_data = builder.build_graph(seed_dois=["10.1038/nature14539"], direction="both")

NetworkAnalyzer

Analyzes the graph topology using NetworkX.

from scholar_graph.analyzer import NetworkAnalyzer

analyzer = NetworkAnalyzer(graph_data)
scores = analyzer.calculate_centrality()
# Returns dict: {"DOI": {"pagerank": 0.05, "in_degree": 10}}

GraphVisualizer

Exports the NetworkX graph to an interactive HTML map using PyVis.

from scholar_graph.visualizer import GraphVisualizer
from pathlib import Path

visualizer = GraphVisualizer(analyzer)
visualizer.export_html(Path("network.html"))

Models

Strictly validated data structures using Pydantic v2.

• GraphData: Holds nodes (dictionary) and edges (list).
• NodeMetadata: Represents a paper (DOI, title, year, citations).
• GraphEdge: Represents a citation link (source -> target).