quinoa-vis-modules

    0.2.3 • Public • Published

    Quinoa vis modules - unified react component for displaying controlled visualizations

    Quinoa vis module exposes a set of scripts aimed at being used in quinoa applications.

    These scripts are of two types :

    • a set of React components displaying a visualization for which the whole state is controlled declaratively, exposing a consistent API despite the difference of data structures and visualization parameters
    • a set of parsing and mapping scripts aimed at manipulating data according to a specific visualization type

    Components are stateful, because they can temporarily have an inner state different from the one provided in their props, in order to allow application-state-independent navigation behaviors in the vis.

    Installation as a dependency

    npm install --save https://github.com/medialab/quinoa-vis-modules
    

    Installation for development

    git clone https://github.com/medialab/quinoa-vis-modules
    cd quinoa-vis-modules
    npm install
    npm run build-storybook
    

    Development

    The project uses storybook to visually test the possible implementations of the component.

    npm run storybook
    

    Npm Scripts

    build : builds dist code for use as dependency

    lint : lints the code (autofix on)

    comb : prettifies scss code

    test : run mocha unit tests on all .spec.js prefixed files present in src

    build-storybook : builds storybook static assets

    storybook : runs a visual testing environment accessible at localhost:6006

    precommit-add-build : as the project uses a pre-commit hook to enforce code quality at each commit, each successful commit automatically adds the build directory

    Module general structure and API

    Module submodules

    import {
      Network, // Network react component
      Map, // Map react component
      SVGViewer, // SVG react component
      Timeline, // Timeline react component
     
      parseNetworkData, // parses a network data representation string
      parseMapData, // parses a map data representation string
      parseTimelineData, // parses a timeline data representation string
     
      mapNetworkData, // consumes data mapping parameters to produce a data representation readable by the network component
      mapMapData, // consumes data mapping parameters to produce a data representation readable by the map component
      mapTimelineData, // consumes data mapping parameters to produce a data representation readable by the timeline component
    } from 'quinoa-vis-modules';

    Examples of use of the components

    Each component receives a declarative description of the state it has to render, plus some callbacks, like so:

    export const MyTimelineContainer = () => (
        <div className="my-timeline-container">
          <Timeline 
            data={timelineData} 
            allowUserViewChange ={true}
            onUserViewChange={(e) => console.log('user changed the view', e)}
            viewParameters = {{
                fromDate: new Date().setFullYear(1900),
                toDate: new Date().setFullYear(1960),
                orientation: 'portrait',
                colorsMap: {
                  main: {
                    cartography: '#F24D98',
                    computation: '#813B7C',
                    mathematics: '#59D044',
                    statistics: '#F3A002'
                  }
                }
              }}
          />
        </div>
    )

    See the story book for more examples of use.

    Data formatting needs

    The data provided to components must always be an object in which each property represents a collection of the data to represent.

    For now, timeline and map require both a single-collection dataset, that is to be provided with an object containing a property main containing the data as an array of js objects.

    Example of data readable by a timeline :

    {
      "main": [
        {
          "title": "Event title",
          "description": "Event description",
          "source": "Event source",
          "category": "computation",
          "startDate": "1943-12-31T23:00:00.335Z"
        },
        // ...
      ]
    }

    Network requires a two-collections dataset, made of a nodes collection and an edges collection.

    {
      "nodes": [
        {
          "id": "229",
          "x": -38.86054,
          "y": -70.56831,
          "size": 3.6082125,
          "label": "Amérique Du Sud",
          "category": "rgb(255,51,51)"
        },
        // ...
      ],
      "edges": {
        {
          "id": "5720",
          "type": "undirected",
          "label": "",
          "source": "229",
          "target": "964",
          "weight": 1
        },
        // ..
      }
    }

    API

    Each quinoa-vis-module component must comply to the following API :

    Variable props :

    • data : ready-to-use data to visualize
    • allowUserViewChange : boolean to specify whether the user can pan/zoom/interact with the view or not
    • viewParameters : object describing the current view of the visualization - the shape of this object depends on the visualization type

    Method props :

    • onUserViewChange : returns data about the triggering interaction and the new view representation

    Common proporties of the viewParameters prop

    The viewParameters must contain all the parameters necessary to render successfully a view of the visualization. The particular structures of the viewParameters of each component is detailed below, but all viewParametersprops share some following subprop :

    • colorsMap : object that specifies how to color objects. First-level keys correspond to data's collections names. Second-level keys are values to look for in a categorical set of values present in objects' data, value are css color descriptions (therefore accepted methods : names, rgb, rgba, hex)
    • dataMap : object that specifies how to interpret's data points' properties in order to populate the visualization. First-level keys correspond to data's collections names. Second-level keys correspond to a visualization's parameter, the value pointing to datapoints' properties names to use for populating the visualization.
    • showCategories : object that specifies how to visually filter objects. First-level keys correspond to data's collections names. Each of them contains an array of strings corresponding the categories to show.

    visualization-specific viewParameters property models

    Timeline

    Example of a viewParameters object for the Timeline component:

    const timelineBaseViewParameters = {
      fromDate: new Date().setFullYear(1900),
      toDate: new Date().setFullYear(1960),
      colorsMap: {
        main: {
          cartography: '#F24D98',
          computation: '#813B7C',
          mathematics: '#59D044',
          statistics: '#F3A002',
          default: 'lightgrey'
        },
        default: 'lightgrey'
      },
      shownCategories: {
        main: ['computation']
      }
    };

    fromDate : date||number

    Start date to use fo displayingr the main view of the timeline.

    toDate : date||number

    End date to use for displaying the main view of the timeline.

    Map

    Example of a viewParameters object for the Map component:

    const mapBaseViewParameters = {
      cameraX: 48.8674345,
      cameraY: 2.3455482,
      cameraZoom: 4,
      colorsMap: {
        main: {
          'accélérée': '#F24D98',
          'normale': '#813B7C',
          default: 'lightgrey'
        },
        default: 'lightgrey'
      },
      tilesUrl: 'http://{s}.tile.stamen.com/toner/{z}/{x}/{y}.png'
    };

    cameraX : number

    Longitude coordinate of the camera center

    cameraY : number

    Latitude coordinate of the camera center

    cameraZoom : number

    Zoom degree of the camera (1 corresponds to the farthest position of camera)

    tilesUrl : string

    Url pattern to use in order to retrieve map tiles.

    Network

    Example of a viewParameters object for the Network component:

    const networkJSONBaseViewParameters = {
      cameraX: 0,
      cameraY: 0,
      cameraRatio: 2,
      cameraAngle: 0,
      labelThreshold: 7,
      minNodeSize: 2,
      sideMargin: 0,
      colorsMap: {
        nodes: {
          1: '#813B7C',
          2: '#41d9f4',
          3: '#64f441',
          default: '#F24D98'
        },
        edges: {
          default: '#c0c6c6'
        },
        default: '#c0c6c6'
      }
    };

    cameraX : number

    Describes the camera center

    cameraY : number

    Describes the camera center

    cameraRatio : number

    Zoom degree of the camera.

    cameraAngle : number

    Rotation angle of the camera.

    labelThreshold : number

    Zoom level starting from which labels can be displayed.

    minNodeSize : number

    Minimum size of network nodes.

    sideMargin : number

    The margin (in pixels) to keep around the graph.

    Pre-commit hook

    The project uses a precommit hook before each commit to ensure the code remains clean at all times. Check out the package.json to learn more about it.

    Install

    npm i quinoa-vis-modules

    DownloadsWeekly Downloads

    4

    Version

    0.2.3

    License

    MIT

    Unpacked Size

    16.5 MB

    Total Files

    86

    Last publish

    Collaborators

    • mydu
    • robindemourat