2. Initialize Scene and Import Data

To creata a visualization, we need to create a scene first:

    let scene = msc.scene();

The returned object is an instance of the Scene class, which is one of the most important classes in Mascot. Mark/glyph creation, data binding, visual encoding and graphical constraints are all accomplished as methods in this class.

Import CSV Data#

Mascot assumes that in Comma Separated Values (CSV) files, the first row contains the column names, and the data is in a long form. For an explanation of the differences between long and wide forms of data, see this Wikipedia article. Section 3 of Tidy Data by Hadley Wickham contains a more technical discussion. To import a CSV file, use the csv function:

    let table = await msc.csv("path/to/file");

IMPORTANT: The csv function is an asynchronous function that returns a promise, hence the await keyword. When the promise is fulfilled, a DataTable object is returned. You need to put the above line of code and any other code that handles the table object in an asychronous function, or use the Promise.then() method to handle the table object. To read more about promise and asynchrous functions, here are some tutorials: link 1, link 2.

When importing a csv file, Mascot automatically infers the data type for each column and parses the values accordingly. An imported data table can be used in one or more scenes.

Import Tree/Hierarchical Data#

Mascot assumes that tree/hierarchical data is represented using a specific JSON format: the JSON representation must be a single object, representing the root of a tree. Non-leaf objects must have a “children” attribute, where the value is an array of objects representing its children. Leaf objects may not have the “children” attribute. The objects can have other attributes. This structure can be nested to represent multiple levels of hierarchy. Below is an example:

{
    "name": "North America",
    "type": "continent",
    "children": [
        {
            "name": "Canada",
            "type": "country"
        },
        {
            "name": "United States of America",
            "type": "country"
        },
        {
            "name": "Mexico",
            "type": "country"
        }
    ]
}

To import a tree dataset, use the treejson function:

    let tree = await msc.treejson("path/to/file");

IMPORTANT: The treejson function is an asynchronous function that returns a promise, hence the await keyword. When the promise is fulfilled, a Tree object is returned. You need to put the above line of code and any other code that handles the tree object in an asychronous function, or use the Promise.then() method to handle the tree object.

Import Graph/Network Data#

Mascot assumes that graph/network data is represented using a specific JSON format: the JSON representation must have two attributes: “nodes” and “links”, the value of each is an array of objects representing the nodes and links in the network. Each node object must have an “id” attribute, which uniquely identifies the node. The “id” value can be a number or a string. Each link object must have a “source” attribute and a “target” attribute, where the values are the node id values. Below is an example:

{
    "nodes": [
        {
            "id": 1,
            "name": "node a"
        },
        {
            "id": 2,
            "name": "node b"
        },
        {
            "id": 3,
            "name": "node c"
        }
    ],
    "links": [
        {
            "source": 1,
            "target": 2
        },
        {
            "source": 1,
            "target": 3
        },
        {
            "source": 2,
            "target": 3
        }
    ]
}

To import a network dataset, use the graphjson function:

    let network = await msc.graphjson("path/to/file");

IMPORTANT: The graphjson function is an asynchronous function that returns a promise, hence the await keyword. When the promise is fulfilled, a Network object is returned. You need to put the above line of code and any other code that handles the network object in an asychronous function, or use the Promise.then() method to handle the network object.