History of aps_citations
The changes to the source code of this entry in the repository, newest first, each with the differences it made to the entry's files. They are also listed on GitLab.
[entries] New entry: aps_citations 40c430c
diff --git a/entries/aps_citations/__init__.py b/entries/aps_citations/__init__.py
new file mode 100644
index 0000000..3f0c57a
--- /dev/null
+++ b/entries/aps_citations/__init__.py
@@ -0,0 +1,212 @@
+#! /usr/bin/env python
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2020-2026 Tiago de Paula Peixoto <tiago@skewed.de>
+#
+# This program is free software: you can redistribute it and/or modify it under
+# the terms of the GNU Affero General Public License as published by the Free
+# Software Foundation, either version 3 of the License, or (at your option) any
+# later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License along
+# with this program. If not, see <http://www.gnu.org/licenses/>.
+
+from .. import *
+
+import csv
+import datetime
+import io
+import json
+import zipfile
+
+title = "American Physical Society citations and authorship (1893-2022)"
+description = r"""Citations among the articles published in the journals of the American Physical Society (APS), and the authors of the articles, from the APS Data Sets for Research (release of 2022), which the APS compiles for research on science and its networks. The data cover all APS journals from their beginning until the end of 2022: Physical Review (its first series, 1893-1912, and the second, from 1913), Physical Review A to E, Physical Review Letters, Reviews of Modern Physics, Physical Review X, Physical Review Applied, Fluids, Materials, Research, Accelerators and Beams, Physics Education Research, PRX Quantum, PRX Energy, and others. There are two networks:
+
+- `citations`: nodes are articles, and a directed edge $(i,j)$ means that article $i$ cites article $j$. The citations are those between APS articles only (references to other publications are not part of the data), as identified by the APS from the reference lists. The data contain 9,833,191 citations; the 204 citations of articles to themselves are kept as self-loops. The nodes are the 720,535 articles of the metadata of the data set, ordered by publication date (and by DOI on the same date), followed by the 4,622 DOIs that appear only in the citations: 69,251 citations come from 4,577 articles without metadata, mostly published in early 2023 or in the magazine *Physics* (and its predecessor *Physical Review Focus*), and 5,933 citations point to 488 articles without metadata, mostly of these magazines. These nodes have no attributes besides their DOI (`has_metadata` is false).
+- `authorship`: a bipartite network of the articles of the metadata (in the same order as in `citations`) and their authors, with an edge between each article and each of its authors. The data identify the authors only by their names, as printed in the articles, so here each distinct name is one author node: the same person appears as several nodes if the name is written differently in different articles (e.g. with or without the full first name), and different people with the same name are a single node. Authors can be persons or collaborations. A name listed twice in the same article gives two parallel edges. Articles without authors in the metadata (e.g. editorials and announcements) are isolated nodes.
+
+The networks have the following properties:
+
+- (Node) `doi`: the DOI of the article (empty for authors).
+- (Node) `has_metadata` (`citations`): whether the article is in the metadata of the data set.
+- (Node) `title`: the title of the article, with its HTML and MathML markup (e.g. for formulas), as given.
+- (Node) `journal`: the abbreviated name of the journal (e.g. `Phys. Rev. Lett.`).
+- (Node) `volume`, `issue`, `page`: the volume, issue, and first page (or article number), as given.
+- (Node) `date`: the publication date (`YYYY-MM-DD`).
+- (Node) `time`: the publication date, in Unix time (0 for articles without metadata, and for authors).
+- (Node) `num_pages`: the number of pages (-1 if not given).
+- (Node) `article_type`: the type of the article (`article`, `rapid`, `brief`, `erratum`, `comment`, `reply`, `letter`, `review`, ...).
+- (Node) `authors` (`citations`): the names of the authors (persons and collaborations), in the order of the article, as given.
+- (Node) `affiliations`: the affiliations of the authors of the article, as given (each listed once).
+- (Node) `disciplines`, `concepts`: the disciplines and the concepts (research areas, techniques, physical systems, ...) of the APS Physics Subject Headings (PhySH) of the article, given for most articles since 2016 (and a few earlier ones).
+- (Node) `subject_areas`: the subject areas of the article, given for articles of Physical Review Applied, Physical Review Research and Physical Review X.
+- (Node) `is_author` (`authorship`): whether the node is an author (otherwise an article).
+- (Node) `name` (`authorship`): the name of the author (empty for articles).
+- (Node) `is_collaboration` (`authorship`): whether the author is a collaboration (otherwise a person).
+- (Edge) `position` (`authorship`): the position of the author in the author list of the article (starting at 1).
+- (Edge) `affiliations` (`authorship`): the affiliations of the author in the article, as given."""
+tags = ['Informational', 'Citation', 'Collaboration', 'Bipartite', 'Unweighted', 'Multigraph', 'Metadata', 'Timestamps']
+url = 'https://journals.aps.org/datasets'
+citation = [('American Physical Society, "APS Data Sets for Research." (2022)',
+ 'https://journals.aps.org/datasets')]
+date_added = '2026-11-16'
+upstream_license = ("APS Data Sets for Research: terms of use",
+ "https://journals.aps.org/datasets")
+restricted = True
+
+upstream_prefix = 'https://downloads.skewed.de/data/aps'
+_citations = "aps-dataset-citations-2022.zip:aps-dataset-citations-2022.csv"
+_metadata = "aps-dataset-metadata-2022.zip"
+files = [((_citations, _metadata), "citations", None),
+ (_metadata, "authorship", None)]
+
+def fetch_upstream(force=False):
+ return fetch_upstream_files(__name__.split(".")[-1], upstream_prefix, files,
+ force)
+
+# For checks only: if set, only this many articles (metadata files) and
+# citations are read
+_check_rows = None
+
+def _unix_time(date):
+ d = datetime.datetime.strptime(date, "%Y-%m-%d")
+ return int(d.replace(tzinfo=datetime.timezone.utc).timestamp())
+
+def _articles(name):
+ """The articles of the metadata, as (date, doi, attributes, authors)
+ tuples, ordered by date and DOI; the authors are (name,
+ is_collaboration, affiliations) tuples."""
+ arts = []
+ with open_upstream_file(name, _metadata, "rb") as f, zipfile.ZipFile(f) as z:
+ for member in z.namelist():
+ if not member.endswith(".json"):
+ continue
+ d = json.loads(z.read(member))
+ cs = d.get("classificationSchemes", {})
+ physh = cs.get("physh", {})
+ affs = {a["id"]: a["name"] for a in d.get("affiliations", [])}
+ authors = [(a["name"], a.get("type") == "Collaboration",
+ [affs[i] for i in a.get("affiliationIds", []) if i in affs])
+ for a in d.get("authors", [])]
+ attrs = dict(title=d["title"]["value"],
+ journal=d["journal"]["abbreviatedName"],
+ volume=d["volume"]["number"],
+ issue=d["issue"].get("number", ""),
+ page=d.get("pageStart", ""),
+ date=d["date"],
+ time=_unix_time(d["date"]),
+ num_pages=d.get("numPages", -1),
+ article_type=d.get("articleType", ""),
+ authors=[a[0] for a in authors],
+ affiliations=list(affs.values()),
+ disciplines=[x["label"] for x in physh.get("disciplines", [])],
+ concepts=[x["label"] for x in physh.get("concepts", [])],
+ subject_areas=[x["label"] for x in cs.get("subjectAreas", [])])
+ arts.append((d["date"], d["id"], attrs, authors))
+ if _check_rows is not None and len(arts) >= _check_rows:
+ break
+ arts.sort(key=lambda x: (x[0], x[1]))
+ return arts
+
+# The article properties: name, type, value for nodes without them
+_props = [("title", "string", ""), ("journal", "string", ""),
+ ("volume", "string", ""), ("issue", "string", ""),
+ ("page", "string", ""), ("date", "string", ""),
+ ("time", "int64_t", 0), ("num_pages", "int32_t", -1),
+ ("article_type", "string", ""),
+ ("authors", "vector<string>", []),
+ ("affiliations", "vector<string>", []),
+ ("disciplines", "vector<string>", []),
+ ("concepts", "vector<string>", []),
+ ("subject_areas", "vector<string>", [])]
+
+def _set_props(g, arts, n_extra, skip=()):
+ "Set the article properties of the first len(arts) nodes of g."
+ for k, t, empty in _props:
+ if k in skip:
+ continue
+ vals = [a[2][k] for a in arts] + [empty] * n_extra
+ if t.startswith("vector"):
+ p = g.new_vp(t)
+ for v, x in zip(g.vertices(), vals):
+ p[v] = x
+ g.vp[k] = p
+ else:
+ g.vp[k] = g.new_vp(t, vals=vals)
+
+@cache_network()
+@coerce_props()
+@annotate()
+def parse(alts=None):
+ name = __name__.split(".")[-1]
+ arts = None
+ for fnames, alt, fmt in files:
+ if alts is not None and alt not in alts:
+ continue
+ if arts is None:
+ arts = _articles(name)
+ index = {a[1]: i for i, a in enumerate(arts)}
+ n_meta = len(index)
+
+ if alt == "citations":
+ edges = []
+ with open_upstream_file(name, _citations, "rb") as f:
+ r = csv.reader(io.TextIOWrapper(f, "utf-8", newline=""))
+ header = next(r)
+ assert header == ["citing_doi", "cited_doi"], header
+ for i, (s, t) in enumerate(r):
+ if _check_rows is not None and i >= _check_rows:
+ break
+ edges.append((index.setdefault(s, len(index)),
+ index.setdefault(t, len(index))))
+ g = Graph(directed=True)
+ g.add_vertex(len(index))
+ g.add_edge_list(edges)
+ del edges
+ g.vp.doi = g.new_vp("string", vals=list(index.keys()))
+ g.vp.has_metadata = g.new_vp("bool",
+ vals=numpy.arange(len(index)) < n_meta)
+ _set_props(g, arts, len(index) - n_meta)
+ else:
+ # the authors, by name, in the order of their first appearance
+ aindex = {}
+ collab = []
+ edges = []
+ pos = []
+ eaffs = []
+ for i, a in enumerate(arts):
+ for j, (aname, is_collab, affs) in enumerate(a[3]):
+ k = aindex.get(aname)
+ if k is None:
+ k = aindex[aname] = len(aindex)
+ collab.append(is_collab)
+ edges.append((i, n_meta + k))
+ pos.append(j + 1)
+ eaffs.append(affs)
+ g = Graph(directed=False)
+ g.add_vertex(n_meta + len(aindex))
+ g.add_edge_list(edges)
+ del edges
+ n_a = len(aindex)
+ g.vp.is_author = g.new_vp("bool",
+ vals=numpy.arange(g.num_vertices()) >= n_meta)
+ g.vp.doi = g.new_vp("string", vals=list(index.keys()) + [""] * n_a)
+ g.vp.name = g.new_vp("string", vals=[""] * n_meta + list(aindex.keys()))
+ del aindex
+ g.vp.is_collaboration = g.new_vp("bool", vals=[False] * n_meta + collab)
+ g.ep.position = g.new_ep("int32_t", vals=pos)
+ p = g.new_ep("vector<string>")
+ # (edges are iterated by source node, not in the order of
+ # their indices)
+ for e in g.edges():
+ p[e] = eaffs[g.edge_index[e]]
+ g.ep.affiliations = p
+ del pos, eaffs
+ _set_props(g, arts, n_a, skip=("authors",))
+ del index
+ yield alt, g