CitationNet

A FastAPI app to generate and display reference and citation traces of a single publication using OpenAlex metadata.

Documentation is available on ReadTheDocs. The javascript part of the package is available at NPM.

Installation

tl;dr Use pip

pip install citationnet

Consider using a clean virtual environment to keep your main packages separated. Create a new virtual environment and install the package

python3 -m venv env
source env/bin/activate
pip install citationnet

Run the app locally

To run the app activate the virtual environment, change in the folder src/citationnet and run

uvicorn interface:app

Now open the address http://127.0.0.1:8000 in your browser and start exploring.

To close the app, press CTRL C in the terminal and close it (on Linux).

Using the interface

The button Usage toggles an explanation of the visual representation of the citation network.

First query

To run a query, enter a DOI or OpenAlex ID and press the submit button. For very highly cited papers, the query time is too long. By default there is therefore a limit on the number of citations for the source publication and all other citations (200 citations). The default value can be changed.

The end of data generation is signaled by a success message stating the filename.

Repeated querying

Query results are saved as JSON files in the media folder of the installed FastAPI package and can be accessed using the dropdown input field at the navigation bar. The filename is generated by the name of the first author and the OpenAlex ID.

Visual representation

The initial graph is viewed from the side. Time ranges from bottom to top, such that newer publications are above the center and older ones below. If viewed from above nodes, farer away from the center have more citations.

Hover over a node to show DOI, year of publishing, fields of research and the number of citations according to OpenAlex. Click a node to open an info box that shows the the publication using it's DOI.

Click and drag inside the window to rotate the graph. Right-click and drag inside the window to move. Scroll inside the window to zoom in or out.

The menu button right next to the sidebar opens and closes the sidebar, which allows controlling the perspective (side or top), node and edge options as well as some basic layout options (cylinder radius, citation value of outer radius, and spacing around input node).

Testing

Tests can be run by installing the dev requirements and running tox.

pip install citationnet[dev]
tox

Building documentation

The documentation is build using sphinx. Install with the dev option and run

pip install citationnet[dev]
tox -e docs

Javascript: Citationnet JS

The javascript part of the software is published as an independent package on npmjs.com.

Generates a 3D graph of publications linked by citations and references. This package is part of the citationnet software.

The package is based on the 3D Force Graph package and defines node parameters such that a cylinder geometry emerges. The z-Axis corresponds to the publication year, such that older publications are arranged towards the bottom. On each year circle, a radial force distributes publications of the given year such, that towards the inner axis, less cited papers are grouped. All publications with citations larger then a fixed limit are arranged on the outer circle.

Interaction with the graph can occur via mouse, via an un-foldable menu or with keyboard shortcuts (Arrow-Up / down to select different camera perspectives). While hovering over nodes, some basic data for the publication is shown. Clicking on a node opens an info box with a link to the source data at OpenAlex.org.

The package is used in an interface, that allows queries to OpenAlex for generating new datasets. The input JSON dataset needs to have the form of a list of nodes and links:

{ 
"nodes": [
    "id": string,
    "publication_year": number,
    "cited_by_count": number,
    "topic": string,
    "fz": number
    ], 
"links": [
    "source": string,
    "target": string,
    "year": number,
    "level": string
    ]
}

where nodes are dictionaries containing an id, publication year, cited by count, fz and topic key. Additionally, the source publication used for generating the dataset contains the key isSource. For each publication a z-coordinate value fz is precalculated during dataset generation, corresponding to the scaled distance in years to the source publication, e.g. 5*(1995 - 2020) for a publication in 2020 which references a paper from 1995.

The links contain information about source and target nodes, the year of the link and a level information. See network code of the interface part for details MPIGEA / Interface

Development

The package is written in Typescript and includes some CSS definitions for the info box and options menu design. The configurations can be found at the source code repo at the MPIGEA / Javascript.

To build a new version locally run

npm run build

to build a new version.

To run the implemented tests run

npm run test

To calculate the hash of a new version to be used in the Content Security Policy header use the following one-liner for each file (js/css)

cat citationnet.(css|js) | openssl dgst -sha384 -binary | openssl base64 -A

Known limitations

Roadmap

Currently, no further development is planned.

Kindly reach out to us, if this package could be valuable for your work.

Funding information

The development was originally part of the research project ModelSEN

Socio-epistemic networks: Modelling Historical Knowledge Processes,

in Department I of the Max Planck Institute for the History of Science, Berlin, Germany and funded by the Federal Ministry of Education and Research, Germany (Grant No. 01 UG2131).

The current iteration was created as part of outreach initiatives of the Max Planck Institute for Geoanthropology, Jena, Germany