citation_network
Build a direct-citation network from a set of papers. Fetch references, keep only internal citations, and compute main paths (SPC weights, local/global paths, key routes).
Instructions
Direct-citation network within a set of papers, in one call: fetches every paper's reference list, keeps only the references to other papers in the set, and runs main-path analysis (SPC weights, local and global main path, key routes). Give ids (Scopus IDs/EIDs; with source='openalex', DOIs or OpenAlex IDs) or a query. Completeness: each list is compared with an independent reference count (Crossref, else OpenAlex, else Semantic Scholar; the source is reported per paper); short = fewer than 90% of the comparison count and at least 5 references missing (SCOPUS_COMPLETENESS_RATIO, SCOPUS_COMPLETENESS_MIN_MISSING). Papers whose references could not be loaded or parsed are listed, retried once after rate limits, and the main path is marked provisional while any are missing. Likely duplicate records are listed. Writes JSON, Pajek .net (arcs from cited to citing, SPC weights; Pajek, VOSviewer, Gephi) and an edge CSV. Cost: one reference request per paper (cached). Sets over about 50 papers may return a job ID: poll job_status, then job_result.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | The papers (up to 1000). Use this or query. | |
| page | No | With inline='full': which page of nodes (1-based). | |
| query | No | Search query defining the set, instead of ids. | |
| scope | No | Restrict to journals, by ISSN: a list of ISSNs, or a basket name ('basket_of_eight' / 'ais8': the AIS Senior Scholars' Basket of Eight). ISSNs are used rather than journal names, which Scopus spells inconsistently. | |
| inline | No | What the reply carries besides the file paths. 'summary': counts, flags and paths. 'edges' (default): also every edge as a compact line (up to 2,000). 'nodes': one compact line per paper (ID, author year, venue, references retrieved/reported, comparison count and source, completeness, error) plus the edges: node-level data for callers that cannot read the server's files, about 25k characters for 150 papers. 'full': the corpus as JSON, paged by page/page_size nodes. | edges |
| source | No | Data source. 'scopus' (default) needs subscriber entitlement for search, citations and references. 'openalex' needs none: IDs may be DOIs, OpenAlex work IDs (W...), or Scopus IDs (resolved to a DOI via Scopus metadata), and results carry OpenAlex IDs. Never mix sources within one analysis. | scopus |
| weight | No | Traversal weight for the main paths and key routes: 'spc' (search path count, source-to-sink paths), 'splc' (search path link count: paths starting at any paper), 'spnp' (search path node pair: paths between any two papers). Liu & Lu 2012. | spc |
| page_size | No | With inline='full': nodes per page (default 50). | |
| key_routes | No | Number of top-SPC key edges to extend into key-route main paths (Liu & Lu 2012; default 10, 0 = none). Key edges that extend into the same route are merged. | |
| robustness | No | Also compute the global main path under all three weights and report the papers they share: a path that survives a change of weight is a finding, one that does not is partly an artefact of the weight. | |
| corpus_file | No | A corpus file from import_records, instead of ids or query. | |
| max_results | No | With query: how many papers to include (default 300). | |
| edge_contexts | No | Also gather citation contexts for every edge (Semantic Scholar; one request per citing paper, cached), give each a draft transmission label, and write a coding sheet for two coders. Slow without a Semantic Scholar key; runs as a job past the sync budget. | |
| construct_terms | No | With edge_contexts: the construct for the draft labels, e.g. ['organizing vision']. | |
| key_route_search | No | How key edges are extended: 'local' follows the heaviest adjoining edge; 'global' takes the heaviest whole path to and from the key edge. | local |
| check_retractions | No | Flag retracted, withdrawn or concern-flagged papers (Crossref / Retraction Watch; default true). | |
| max_context_edges | No | With edge_contexts: most edges to examine, heaviest SPC first (default 300). | |
| check_completeness | No | Compare each reference list with an independent count (default true). |