betsydupuis / oligrapher

JavaScript app for displaying annotated network graphs based on data from LittleSis

Oligrapher

Oligrapher is a JavaScript app for visualizing network graphs. It allows a user to design a nice-looking network graph using a combination of imported or manually entered data, and to create a collection of annotations for a graph.

Oligrapher was originally developed by LittleSis before it was separated into a standalone library. LittleSis has a large collection of maps created with Oligrapher.

Oligrapher is built with React and Redux and is bundled with esbuild

• Features
• Install
• Development
• Data Schema
• API
• Data Sources
• Editing Guide

Features

• easily create and display network graphs
• tell a story about networks with click-through series of annotations
• add images, labels, links, and captions
• customize graph layout by dragging nodes and edges
• import data from LittleSis and other APIs
• undo and redo edits to a graph
• runs on all modern web browsers
• export map as svg or jpeg
• save map to LittleSis.org account

Install

To run Oligrapher app in a web page, include oligrapher.js and oligrapher.css on your page and create a element for the map:

<link rel="stylesheet" href="oligrapher.css">
<script src="oligrapher.js"></script>

<div id="example-oligrapher"></div>

<script>
const oli = new Oligrapher({ isEditor: true, domId: "example-oligrapher" })
</script>

See defaultState.ts for configuration options

Development

To run this app in development mode:

git clone https://github.com/public-accountability/oligrapher
cd oligrapher
npm install
npm run dev
npm run serve

Then point your browser to localhost:8000 to view a blank graph.

Also available:

• example maps : /exxon.html & /dev.html
• larger map with annotations : /dev.html
• map in embedded-mode using an inframe : /article.html

Production build: npm run build

Development build: npm run build-dev

Build css: npx sass app/oligrapher.scss build/oligrapher.css --style=compressed

Run tests: npm test

Data Schema

Node Attributes

• id: (required) a string uniquely identifying the node
• name: (required) a string, which will be displayed underneath the node (on multiple lines if necessary)
• scale: relative size of node (1 is default and smallest)
• status: default is normal, can also be highlighted or faded
• color: hexcodeof node color
• image: image URL or dataurl
• url: optional source URL
• x: x-coordinate of the node's position
• y: y-coordinate of the node's position
• edgeIds array of connected edges, calculated internally

Edge Attributes

• id: (required) an integer or string uniquely identifying the edge
• node1_id: (required) equal to the first node's id
• node2_id: (required) equal to the second node's id
• label: (required) label appearing above the edge
• url: optional source URL
• scale: relative thickness of edge (1 is default, 2 is twice as thick, etc)
• status: default is normal, can also be highlighted or faded
• arrow: Direction of the arrow: 'left', 'right', 'both' or false (default is false)
• dash: the kind of dash displayed in edge's line (default is null, a solid line)
• cx: x-coordinate of the control point for the edge's quadratic Bezier curve, relative to the midpoint of the straight line between the two nodes (if not specified, this is computed to display a slight curve)
• cy: y-coordinate of the control point for the edge's quadratic Bezier curve, relative to the midpoint of the straight line between the two nodes (if not specified, this is computed to display a slight curve)

Caption Attributes

• id: (required) an integer or string uniquely identifying the caption
• text: (required) the caption's text content
• x: x-coordinate of the caption's position
• y: y-coordinate of the caption's position
• size: caption font-size
• font: caption font-family
• weight: caption font-weight

Annotation Attributes

The annotations array should conforms to the following schema:

[
  {
    header: "The Revolving Door",
    text: "Goldman Sachs has many former executives with top positions in the federal government.",
    nodeIds: [...],
    edgeIds: [...],
    captionIds: [...]
  },
  {
    header: "Treasury Department",
    text: "Former Treasury Secretary Robert Rubin was co-chair of Goldman before joining the Clinton Administration in 1993." ,
    nodeIds: [...],
    edgeIds: [...],
    captionIds: []
  },
  ...
]

• header: (required) a header to be displayed above the annotation
• text: (required) the text body of the annotation, with optional HTML markup
• nodeIds: (required) an array of ids of nodes to highlight from the underlying graph (can be empty)
• edgeIds: (required) an array of ids of edges to highlight from the underlying graph (can be empty)
• captionIds: (required) an array of ids of captions to highlight from the underlying graph (can be empty)

If no node, edge, or captions are highlighted, the graph will have its normal appearance when viewing the annotation. If there are highlights, non-highlighted content will appear faded.