polisci-vis

1.0.2 • Public • Published

polisci-vis

View a demo!

This interactive demo visualizes countries with similar website blocking patterns. See our data processing repository for how we generated our data source.

Getting started

polisci-vis is a Node.js module. It can be installed via npm:

npm install polisci-vis

Creating a visualization

Note: Refer to our demo repository for an example implementation.

To include this visualization on a webpage, take the following steps:

  1. Import the createVisualization function from polisci-vis in your JS file.
import { createVisualization } from 'polisci-vis';
  1. Import your bundled JS file in your base HTML file below the div in which the visualization will appear:
<div id='visContainer'></div>

<script src="index.bundle.js"></script>
  1. Inside the JS file, call the function createVisualization to initialize the display.
<script>
createVisualization({
    visId: 'visContainer',
    data: data,
    numIncrements: 5,
    minSimilarity: 0,
    maxSimilarity: 1,
    digitsRounded: 2,
    colorScheme: 'schemeBlues',
    defaultMode: 'force',
    enabledModes: ['force'],
    tableProperties: ['similarity'],
    tableColumnNames: ['Similarity'],
    showTable: true,
    worldMapProperties: {
    	visibleProperty: 'similarity',
        visHeight: '750px',
        defaultFill: '#d3d3d3',
        selectedFill: '#228B22',
        highlightedFill: 'orange',
        highlightBorderWidth: 2,
        selectedCountry: 'USA',
        interactive: true,
    },
    forceProperties: {
    	visibleProperty: 'similarity',
        visHeight: '750px',
        selectedCountry: 'CHN',
        linkMultiplier: 5,
        interactive: false,
    },
});
</script>

The function accepts the following required parameters:

  • visId: string; the id of the div that the visualization will be in
    • defaults to 'visContainer' (but will error if this id is not on the embedding page)
  • data: a JSON object that follows the formatting described in this README
  • defaultMode: string; the mode of the visualization that is initially visible to the user
    • defaults to 'worldMap'
    • possible values: 'worldMap', 'force'

The following parameters are optional:

  • numIncrements: int; the number of increments in the visualization legend
    • defaults to 5
  • minSimilarity: int / float; the minimum country-pair similarity value
    • defaults to 0
  • maxSimilarity: int / float; the maximum country-pair similarity value
    • defaults to 1
  • digitsRounded: int; the number of digits past the decimal point that any table values should be rounded to
    • defaults to 2
  • colorScheme: string; the color theming for the visualization
    • must be a valid color scheme from the d3-chromatic library
    • sequential color scales are recommended for the most meaningful visual results
    • defaults to 'schemeBlues'
  • enabledModes: list of strings; the modes of the visualization that the user can toggle between
    • defaults to ['worldMap', 'force']
    • only supports combinations of 'worldMap', 'force' (the 2 currently supported modes)
  • tableProperties: list of strings; the input data country-pair-specific properties that will be visible in the similarity table
    • defaults to []
    • if tableProperties = [], the similarity table will not appear
  • tableColumnNames: list of strings; the corresponding column labels that will be visible in the similarity table, and radio button labels for displaying layered data
    • defaults to []
    • if tableColumnNames = [], the similarity table will not appear
  • showTable: boolean; determines whether or not the similarity table is visible
  • worldMapProperties: worldMap-specific properties
    • visibleProperty: the country-pair property that will be visible by default in the current mode
      • should be specified even if there is only one unique pair property in the dataset
      • defaults to 'similarity'
    • visHeight: string; height in pixels of the visualization's worldMap mode e.g. '750px'
      • defaults to '750px'
    • defaultFill: string (hex or color name); color of countries on map for which no data is available
      • defaults to '#d3d3d3'
    • selectedFill: string (hex or color name); color of currently selected country on map
      • defaults to '#228B22'
    • highlightedFill: string (hex or color name); color of currently moused-over / highlighted country on map
      • defaults to 'orange'
    • highlightBorderWidth: int; border width in pixels of currently moused-over / highlighted country
      • defaults to 2
    • selectedCountry: initially selected country in map mode
      • defaults to 'USA'
    • interactive: boolean; determines whether viewers can interact with the visualization to change its appearance (e.g. clicking)
      • defaults to true
  • forceProperties: force graph-specific properties
    • visibleProperty
    • visHeight
    • selectedCountry: initially selected country in force mode
      • no default value -- if not passed in, the full force graph with all input data will be visible
    • linkMultiplier: int / float; constant by which edge lengths are multiplied in the force graph for visual reasons (i.e. so edges aren't too short)
      • defaults to 5
    • interactive

It is not necessary to pass in mode-specific properties if the mode is not within enabledModes for the specific visualization. For example, if enabledModes does not contain force, forceProperties may be omitted from the passed properties.

Note: Parameter order doesn't matter, as all arguments are passed in map format.

API

You can also call other functions to manipulate visualization state after initializing with createVisualization:

loadData(options, data) Description: Changes the data object that populates the visualization. The new data object should follow the formatting directions specified in the data/ directory README. Parameters:

  • options: the current options object
  • data: the new data object

Example call:

const newData = JSON.parse(require('./new_data.json'));

loadData(options, newData);

selectCountry(countryName, options) Description: Sets the selected country in the current mode. Parameters:

  • countryName: the name of the country to be selected e.g. 'Norway', 'United States', etc.
  • options: the current options object

Example call:

selectCountry("United States", options);

showDataTable(options) Description: Shows the data table with country-pair properties under the visualization. Parameters:

  • options: the current options object

Example call:

showDataTable(options);

hideDataTable(options) Description: Hides the data table with country-pair properties under the visualization. Parameters:

  • options: the current options object

Example call:

hideDataTable(options);

changeLayer(options, layer) Description: Changes the visible data layer in the current mode. Parameters:

  • options: the current options object
  • layer: the property name that will be visible in the current mode

Example call:

changeLayer(options, 'similarity');

disableLayering(options, layer, layerName) Description: Disables data layering, leaving only a specified layer visible without toggle options. Parameters:

  • options: the current options object
  • layer: the property name that will be the only property visible in the visualization
  • layerName: the column label name corresponding to layer

Example call:

disableLayering(options, 'similarity', 'Similarity');

enableLayering(options, layers, layerNames) Description: Enables data layering, with toggling available between specified layers. Parameters:

  • options: the current options object
  • layers: an array of property names that can be toggled in the visualization
  • layerNames: the column label names corresponding to layers

Example call:

enableLayering(options, ['similarity', 'x'], ['Similarity', 'X_Prop']);

disableInteractive(options, mode) Description: Disables clickable changes / interactivity in the specified mode. Parameters:

  • options: the current options object
  • mode: the mode to disable interactivity

Example call:

disableInteractive(options, 'force');

enableInteractive(options, mode) Description: Enables clickable changes / interactivity in the specified mode. Parameters:

  • options: the current options object
  • mode: the mode to enable interactivity

Example call:

enableInteractive(options, 'force');

getState(options) Description: Returns a condensed current state of the visualization, containing some manipulated options attributes. Useful for testing. Parameters:

  • options: the current options object

Example call:

getState(options)

setState(options) Description: Sets the state of the visualization to the specified options object and reloads the visualization. Parameters:

  • options: the new options object

Example call:

setState(options)

Repository structure

  • data/: marshalled data produced by our data processing repo
  • js/: includes individual JS files for implementing specific visualization modes
  • css/: includes CSS styling files
  • libraries/: code dependencies unavailable via npm install
  • local_country_variables/: logic for marshalling country names

License

BSD-3

Keywords

none

Install

npm i polisci-vis

DownloadsWeekly Downloads

1

Version

1.0.2

License

BSD-3-Clause

Unpacked Size

245 kB

Total Files

17

Last publish

Collaborators

  • lbhattac