2. Initialize Scene and Import Data

To create 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 the top-level container in Mascot. Marks, glyphs, guides, and visual encodings are created through scene methods, while data-join and constraint operations are available as standalone msc.* functions.

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 asynchronous function, or use the Promise.then() method to handle the table object. To read more about promises and asynchronous 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 msc.treeJSON function:

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

IMPORTANT: The msc.treeJSON function is asynchronous and 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 asynchronous 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 msc.graphJSON function:

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

IMPORTANT: The msc.graphJSON function is asynchronous and 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 asynchronous function, or use the Promise.then() method to handle the network object.

2. Initialize Scene and Import Data

Import CSV Data#

Import Tree/Hierarchical Data#

Import Graph/Network Data#

Import CSV Data

Import Tree/Hierarchical Data

Import Graph/Network Data