public-accountability/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.

oligrapher's Issues

Prioritize Recent and Current relationships in the add connections search

Feature: links to database editing views from within graph editor

Imagine the following scenario:

• I'm editing a graph in the new editor
• I've added a node
• I select the node then click "Add Connections" to search for a connection to add
• I perform the search and discover that the connection is not in the database.

At this point it would be great if there was a link I could click directly within the UI to add the new connection to the database. This link could simply jump to the right part of the database editor in a separate tab, and it would be more convenient than manually navigating to it.

The same may apply for creating a new node. I note there is already a clickable link for creating a new node, but it looks like maybe it only creates it in the current graph rather than in the database?

Feature: reorder annotations

The sequence of annotations is defined by the order in which they are created. For a more intuitive editing of the narration, it could be nice to reorder the annotations with drag and drop.

Littlesis-rails issue !

Hello
sorry to bother you here
As there is no issue manager for the littlesis repo, i'm posting this here
I followed the developer document to install through docker, I'm on debian 12 (testing)
Everything runs smooth except in the end
http://localhost:8080 (or 8081) gives me an error about db migrations 👍

ActiveRecord::PendingMigrationError
Migrations are pending. To resolve this issue, run:
bin/rails db:migrate RAILS_ENV=development
You have 197 pending migrations:
20180117165745_change_int_length_for_address_category.rb
20180117190400_add_index_on_created_at_to_versions.rb
20180122192339_create_government_advisory_and_research_institute_enity_extensions.rb
20180123184642_add_new_fields_to_business.rb
20180123192048_create_cmp_entities.rb

(follow 197 migrations)

If i run a shell to try the migration, I get

bin/rails db:migrate RAILS_ENV=development
== 20180117165745 ChangeIntLengthForAddressCategory: migrating ================
-- remove_foreign_key(:address, :address_category)
rails aborted!
StandardError: An error has occurred, this and all later migrations canceled:

Table 'address' has no foreign key for address_category
/littlesis/db/migrate/20180117165745_change_int_length_for_address_category.rb:3:in 'change'

Caused by:
ArgumentError: Table 'address' has no foreign key for address_category
/littlesis/db/migrate/20180117165745_change_int_length_for_address_category.rb:3:in 'change'
Tasks: TOP => db:migrate
(See full trace by running task with --trace)

I'd like to setup a local littlesis version to work offline
and perhaps, one day, help others with your tool

Cannot add links to multiple custom edges/autofills links from other edges

You can only add a custom link to one custom edge at a time. When you add the link in edit mode it looks the link appears to be autofilled in all of the other edges but does not save those links.

Example: I added the link to one edge and then when i went to add it to others the link was already in the box. but when i saved the link was only actually added to the original edge
Then when I tried to add the link to multiple edges by deleting the auto-filled link, it would still only add to one edge. https://littlesis.org/maps/3001-mvp-top-owner-operator-buoyed-by-big-banks-wall-street

Edges are not responsive, not able to separate with multiple edges [large]

"Edges weren’t responsive to some users so when multiple edges popped up between entities they were not able to separate them. (Same issue after saving, closing, reopening)"

Reported by Gin

Using Oligrapher in a static gen'd site

Is there example code as to how to embed in Jekyll for a static GitHub-Pages deployment?

I'm wondering if it is even possible..

Intergrate LittleSis tags

It should be possible to do the following:

• Limit search by tag
• Filter the add connections by tag
• Prioritize interlocks connections based on tag

Perhaps this can enabled via a "tag mode"

Feature: Nodes and edges have additional metadata

As a diagrammatic storyteller, I would like to be able to add descriptions, media and further data (geolocation?, timestamps?) to nodes and edges, in order to be able to provide additional context next to annotations.

This would provide a more interactive perception during individual exploration of the graph, when not following the sequence of annotations.

Clicking on map (or preforming another action) should trigger the "find nodes" dropdown to be closed

Demo site graph slowly scrolls off the bottom of the screen

After cloning and npm install I do npm run serve

... then I navigate to localhost:8000/dev/ I see the graph scroll off the bottom of the page, yet I'm not touching the mouse or keyboard. See hastily made screencap with the chart nearly off the bottom of the page after a couple of seconds:

Pretty sure that shouldn't happen. I'm using Chrome v110.0.5481.181 (Official Build) (64-bit), It does the same for Firefox too.

Feature: keyboard shortcuts

Hi there, just watched your Zoom presentation on the new version and it looks awesome. Kudos on the great work!

As mentioned, it would be great if there were keyboard shortcuts for the most common graph editing operations. For example:

• + and - for zooming in and out
• n for adding a new node
• t for adding text
• i for interlocks

and so on.

Add an option to display labels/text for an edge without hovering over it

This is a feature request, not a current issue. It would be handy to have an option to display labels/text for an edge, without having to hover over the edge, as an option by edge. For some edges/connections/relationships, the amount of a contribution, for example, is worth displaying on the map; for others, the label/text is not necessary, or will just add more clutter.

Save button: position and signaling the need to save

As a user, I wish to edit the map and have my changes picked up by the mapping system.

For this to succeed, I need to find the Save button in the lower left corner of the screen, and need to use it.

For easier discoverability of it, e.g. on a 4K screen, it could be nice to discover possibilities to place it next to a map's headline, in the top-right, or in the bottom-right.

Additionally, it would be helpful to know if there are changes that need to be saved. To indicate the need to save latest changes to the map, the Save button could change its colour to something like yellow or orange.

Remove bootstrap from css or make a build version without it

Including bootstrap inside Oligrapher can creates conflicts with other styles on the page that is using Oligrapher. I propose we either find the styles from bootstrap that we use and create on our stylesheet for oligrapher or create a build option that allows an external bootstrap to be used and/or other stylesheets.

when you click out of node search box or delete search term, search results should go away

Option to export to SVG image

(with embedded images)

Fix self-pointing arrows

If an entity has relationships to itself, there is a circular arrow that looks wierd. Eg: Trump donating to himself.

original: skomputer/oligrapher#59

Image and URL fields do not get updated

As a user in edit mode, I want to switch between nodes with different metadata and edit them accordingly.

Now, when having a node selected that has an image and a link set, and switching to another where one or the two of those settings are not present, the editor interface does not clean the input fields from the previous contents.

Nodes taking on pictures from other nodes bug

skomputer/oligrapher#60

If I change the size of a node with a picture, and then I change the size of a node without a picture, the second node then, after re-sizing, acquires the image from the first node.

remove self-relationships

nodes shouldn't be allowed to have relationships to themselves – either from the database or created by user.

it's possible right now to create these "self relationships" in map editor. it's also possible to add self relationships in database, but we have to keep that due to situations where politicians are giving money to their own campaign accounts, it's just how our data model works.

Add X entities of Y relationship category to map

Some users have a need for the Oligrapher 2.0 method of adding connections. This could be a new component or enabled only through a setting.

Feature: quick zooming / panning via mouse / touchpad

Currently it seems that the new Oligrapher supports zooming via the + / - icons at the top right of the map, and panning via click-drag on an empty area of the map. It would be great if there were more ways to pan and zoom with the mouse and touchpad. Some conventional ways implemented in many other programs are as follows:

• Mouse wheel to pan up/down
• Mouse wheel while holding Shift to pan left/right
• Mouse wheel while holding Control to zoom in/out
• Two finger drag on touchpad to pan in any direction
• Two finger drag up/down on touchpad while holding Control to zoom in/out

These could help make the UX a bit more convenient and friendly.

demo use without login

original: skomputer/oligrapher#61

On littlesis.org there's no apparent way to utilise the oligrapher and explore the potential maps of connection without signing up and logging in.

For something like littlesis, I cant be the only one who's tinfoil hat gets itchy at that.

I had hoped it would serve like the old theyrule.net would, except more open to wiki-esq crowd sourced data, and not requiring proprietary malware... but at least with theyrule.net you could explore it without having to hand over your identification papers at the gate. Could be an anonymous ip passing by, getting familiarised on the fly with the very pertinent useful data. Like checking a weather site, or a currency market site, you get to see and peruse and specify what of it you want to see and how, and no login is necessary.

Sorry if wrong place for this feature request, and is entirely a re-configuration decision of littlesis.org, n not anything intrinsic to the oligrapher software.

The button reads: Get started on a new map
and under it, the next line reads: or sign up for a LittleSis account

"or". Which is easily interpreted as suggesting one does not need to sign up, but then if you click the button, it takes you to a login page, with a line stating that you do need to log in to use it.

It seems non-login access would fit little sister's promoted remit much better, and login-only access would fit the remit of big brother better.

Please is it possible to have non-login access?

Map image urls should not accept non https links

Feature: Nodes and edges appear when advancing in the sequence of annotations

As a diagrammatic storyteller, I want to introduce my audience to new concepts and relations slowly, in order to not overwhelm it cognitively.

For a more surprising graph map story, it can be interesting to explore ways to display certain nodes and/or edges only from specific annotations on.

extra blank space appears at bottom of embedded maps without annotations