Metadata-Version: 2.3
Name: citationnet
Version: 2.1.0
Summary: Create a scientific network visualization.
Project-URL: Project Homepage, https://modelsen.gea.mpg.de
Project-URL: Homepage, https://gitlab.gwdg.de/mpigea/dt/citationnet-interface
Project-URL: Issues, https://gitlab.gwdg.de/mpigea/dt/citationnet-interface/-/issues
Author-email: Malte Vogl <vogl@gea.mpg.de>
License-File: AUTHORS.md
License-File: LICENSE.md
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: fastapi
Requires-Dist: httpx
Requires-Dist: jinja2
Requires-Dist: pandas
Requires-Dist: python-multipart
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: uvicorn
Provides-Extra: dev
Requires-Dist: myst-parser; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: sphinx; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# CitationNet

![NPM Version](https://img.shields.io/npm/v/citationnet.svg) ![PyPI](https://img.shields.io/pypi/v/citationnet?label=pypi%20package) [![Documentation Status](https://readthedocs.org/projects/citationnet/badge/?version=latest)](https://citationnet.readthedocs.io/en/latest/?badge=latest) 


A FastAPI app to generate and display reference and citation traces of a single publication
using [OpenAlex](https://openalex.org/) metadata.

Documentation is available on [ReadTheDocs](https://citationnet.readthedocs.io/). The javascript part of the package is available at [NPM](https://www.npmjs.com/package/citationnet).

# Installation

tl;dr Use pip

``` bash
pip install citationnet
```

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

``` bash
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
```bash
uvicorn interface:app
```

Now open the address [http://127.0.0.1:8000](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`.

~~~bash
pip install citationnet[dev]
tox
~~~

## Building documentation

The documentation is build using _sphinx_. Install with the _dev_ option and run

~~~bash
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](https://github.com/vasturiano/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:
```YAML
{ 
"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](https://gitlab.gwdg.de/mpigea/dt/citationnet-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](https://gitlab.gwdg.de/mpigea/dt/citationnet).

To build a new version locally run 
```bash
npm run build
```
to build a new version. 

To run the implemented tests run
```bash
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)
```bash
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](https://modelsen.gea.mpg.de)

> 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