--- name: citation-network-e73f7809dd97 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](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//`. - 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 ```bash python scripts/init_run.py ``` This creates a new run folder: ```text outputs/runs// config.json data/ outputs/ ``` ### 2) Prepare the citation CSV (minimal) Create `citations.csv` and place it into: ```text outputs/runs//data/citations.csv ``` Minimal CSV format: ```csv source,target Paper A,Paper B Paper A,Paper C ``` Recommended DOI-based identifiers: ```csv source,target 10.1234/abcd.1,10.1234/abcd.2 10.1234/abcd.1,10.1234/abcd.3 ``` ### 3) Confirm configuration Open: ```text outputs/runs//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 ```bash 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: ```csv 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//`. - 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. --- Source attribution: aipoch Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/scientific-skills/Evidence%20Insight/citation-network/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 AIpoch Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: aipoch Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/scientific-skills/Evidence%20Insight/citation-network/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Education & Research Roles: Data Analyst, Market Research Analyst, Researcher Specialties: API, Database Tools: Gephi, Networkx, Pandas, Python, Pyvis Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 3e0ea59bfd5197bbdf5e3bdd0f6572f51ea80793f9106f23af12b74bb267e247