citation-network

name	citation-network
description	Build and visualize a citation network from a source/target CSV to identify key papers, communities, and emerging hotspots; use when you have citation pairs and need fast literature review or trend analysis.
license	MIT
author	AIPOCH

Source: https://github.com/aipoch/medical-research-skills

When to Use

• You have a citation relationship table (who cites whom) and want to quickly turn it into a directed network for analysis.
• You are conducting a literature review and need to identify influential papers (high in-degree / centrality) and core clusters.
• You want to detect community structures (research subfields) and compare them across time or datasets.
• You need an interactive, shareable visualization (HTML) or a Gephi-importable graph file (GEXF).
• You are positioning a new project and want evidence of research hotspots and bridging papers between communities.

Key Features

• Builds a directed citation graph from a minimal CSV containing source and target.
• De-duplicates nodes by identifier (DOI recommended; otherwise unique titles).
• Exports:
  • citation_network.gexf for Gephi and other graph tools
  • network_metrics.json for basic network statistics
  • citation_network.html for interactive browser viewing (auto-generated by the build script)
• Run-directory workflow to keep each execution reproducible and isolated under outputs/runs/<timestamp>/.
• Optional input encoding control to avoid garbled characters (e.g., UTF-8 / UTF-8-SIG).

Dependencies

• Python 3.10+
• pandas >= 2.0
• networkx >= 3.0
• (Optional, for HTML visualization) pyvis >= 0.3

Example Usage

1) Initialize a run directory

python scripts/init_run.py

This creates a new run folder:

outputs/runs/<timestamp>/
  config.json
  data/
  outputs/

2) Prepare the citation CSV (minimal)

Create citations.csv and place it into:

outputs/runs/<timestamp>/data/citations.csv

Minimal CSV format:

source,target
Paper A,Paper B
Paper A,Paper C

Recommended DOI-based identifiers:

source,target
10.1234/abcd.1,10.1234/abcd.2
10.1234/abcd.1,10.1234/abcd.3

3) Confirm configuration

Open:

outputs/runs/<timestamp>/config.json

Ensure the configured input filename and column names match your CSV (at minimum source and target). If you see garbled characters, set an explicit encoding (e.g., utf-8 or utf-8-sig) via an input_encoding field if supported by the config.

4) Build the citation network

python scripts/build_citation_network.py

The build script will also generate the HTML automatically (you do not need to run scripts/export_gexf_html.py manually).

5) Inspect outputs

Expected outputs under the same run directory:

• citation_network.gexf (import into Gephi)
• network_metrics.json (node/edge counts, density, etc.)
• citation_network.html (open in a browser)

Implementation Details

Data Model

• Nodes: papers, identified by the value in source/target (DOI preferred; otherwise a unique, consistent title string).
• Edges: directed citations source -> target.

Input Requirements and Constraints

• The network builder reads only the source and target columns.
• Additional columns (e.g., author/year/venue) are ignored by the current scripts.
• If you need metadata, maintain a separate table for downstream joining/annotation (not consumed by the builder), for example:

id,title,authors,year,doi
10.1234/abcd.1,Paper A,"Zhang, Wei; Li, Ming",2021,10.1234/abcd.1
10.1234/abcd.2,Paper B,"Wang, Fang",2019,10.1234/abcd.2

Run Directory Standard

• Always run python scripts/init_run.py before an execution to create a new run directory.
• All inputs, configs, and outputs must remain inside outputs/runs/<timestamp>/.
• By default, scripts operate on the latest run directory under outputs/runs/.

Metrics and Analysis (Conceptual)

• Basic network statistics are exported to network_metrics.json (e.g., node/edge counts, density).
• Typical downstream analyses include:
  • centrality (degree, betweenness)
  • community detection (e.g., Louvain), if enabled/implemented in the pipeline

Common Failure Modes

• Garbled characters: ensure CSV is UTF-8/UTF-8-SIG; set input_encoding in config.json if available.
• Duplicate nodes: identical identifiers are treated as the same node; prefer DOIs or enforce unique titles.
• Empty or missing output: verify the CSV header names match the configured source/target columns.

Related References

• Data cleaning checklist: references/data-cleaning-checklist.md
• Network metrics notes: references/network-metrics-notes.md
• Additional documentation: references/README.md

When Not to Use

• Do not proceed when required input files, identifiers, parameters, or context are missing — ask the user to provide them first.
• Do not assume capabilities beyond this skill's declared scope when the user requests external operations or inferences.
• Do not proceed without user confirmation when overwriting existing results, executing high-cost batch operations, or expanding task scope.

Required Inputs

Field	Required	Format/Source	Example	If Missing
User task description	Yes	Text	Research question, writing goal, analysis objective	Stop and ask user to provide
Primary input material	Depends on task	Text, file path, ID, table, or literature	PMID, PDF, CSV, DOCX, keywords, etc.	Specify which material type is missing
Output preference	No	Text	Language, format, target journal, template	Use skill default format

Output Contract

• Primary output: Structured result or target file aligned with this skill's objective.
• Optional output: Intermediate check notes, issue list, supplementary suggestions, or generated file paths.
• Format requirement: Unless the user specifies otherwise, prefer stable, reviewable Markdown or JSON; if the skill's bundled script requires a fixed format, use that format.
• If partially complete: Must explicitly mark as PARTIAL and state which steps are completed and which remain.

Failure Handling

• Missing critical input: Explicitly state which fields, files, or identifiers are missing and pause.
• Script, template, or resource execution failure: Report the failing step, likely cause, and recovery suggestions — do not silently degrade.
• Partial completion only: Return the verified portion first, then list remaining blockers and suggested next steps.

User Checkpoints

• Before executing batch processing, overwriting files, long-running searches, or multi-stage generation, confirm scope and output format with the user.
• Before proceeding when a key judgment is ambiguous, evidence is insufficient, or the workflow is entering the next stage, confirm with the user.

Input Validation

This skill accepts requests that match the documented purpose of citation-network and include enough context to complete the workflow safely.

Do not continue the workflow when the request is out of scope, missing a critical input, or would require unsupported assumptions. Instead respond:

citation-network only handles its documented workflow. Please provide the missing required inputs or switch to a more suitable skill.

Quick Validation

• Check that key scripts, templates, or reference file paths this skill depends on exist.
• Check that the final output contains the core fields, sections, or files specified for this task.
• Check that results clearly mark assumptions, limitations, and incomplete items.