.. _quick_start: Quick Start Guide ================= This chapter is all about how to make use of a running Multinet system. Along the way, you will also learn how Multinet structures data into tables and networks, collected in different workspaces, and how Multinet thinks of multivariate data and multivariate networks. To begin, you will need access to a running Multinet instance (either the official instance hosted at https://multinet.app, or a local instance you have built and run; see :ref:`developer_quick_start` for help). We will follow some steps to illustrate the basic mode of using the system. **0. Log In** All operations that mutate data inside Multinet require authentication. To log in, click on the person icon next to the multinet logo and then click 'Sign in with Google'. Follow the prompts until you're back on the multinet site and you should see your initials where the person icon was. **1. Create a Workspace** Multinet structures all the data it hosts into *workspaces*. A workspace can hold several tables of data, as well as several networks assembled from those tables. Think of a workspace as a dedicated area for related data to be stored. In this tutorial sequence we will be recreating the `Paul Revere dataset `_ as a social network connecting the various Revolutionary War figures to the social clubs they belonged to. To create a workspace to hold the materials for this dataset, use the ``NEW WORKSPACE`` button appearing near the top of the left sidebar. A dialog box will appear asking for the name of the new workspace. Fill this in with ``boston`` and click on the ``CREATE WORKSPACE`` button. This will create the workspace and activate it. In the main panel, you should see two empty columns, headed by ``Networks`` and ``Tables`` respectively. These columns will track all of the data that comes to live in this workspace. **2. Upload Node Tables** Multinet data is tabular data. That is, it is organized into tables, which contain rows of data, each row containing the same columns of data. Each table has a name, and each row has a unique identifier within that table, called a *key*. The key column is always called ``_key`` when the data is stored in Multinet. Every table that you upload to Multinet must have a key column, but the key can be automatically generated by Multinet if you don't have one. We will begin by uploading separate tables to account for the *people* and *clubs* represented in this dataset. First, download :download:`members.csv `; this file contains the names of several historical figures important during the American Revolution, along with some attributes. Next, click on the ``UPLOAD OR CREATE`` button in the top bar, and then click on the ``UPLOAD FILE`` tab. At the top, click on the ``TABLE`` button and then click on the ``Select a File`` field, and then select the ``members.csv`` file you just downloaded. On this same page, now review the automatically generated name of the table, which should be ``members``. If you want to change this name, you can do so now (but note that this will make uploading the edges trickier). Click ``NEXT`` in the bottom right corner when you are ready to proceed. The next stage of uploading is specifying column types for the table. Multinet supports several different types of data, including primary keys, edge sources and targets, strings, booleans, categories, numbers, and dates. For now, we will accept the defaults, which should be ``_key`` as a primary key and ``name`` as a label. Click ``UPLOAD`` in the bottom right corner to proceed. This network contains two *node types*---one to encode the people, and another for the clubs they belong to. Multinet recognizes nodes encoded in different tables as being of different node types, so download :download:`clubs.csv ` and upload it to a ``clubs`` table, using the same procedure as above. You should now see both a ``members`` and a ``clubs`` table listed. You can click on each of these to see the rows of each table. Return to the workspace view by clicking on boston in the top bar or in the workspaces list on the left. **3. Upload an Edge Table** Next we want to specify the topology of this network---that is, the relationship between clubs and members as specified by membership. We need a special table that encodes these memberships, using special attributes ``_from`` and ``_to``. As before, the data doesn't have to in exactly this format (we can specify different column names for the source and target), but it makes things easier if it is. One key thing to note, however, is that the values of these attributes are not the names of the nodes involved, but rather *node IDs*. Node IDs are always of the form ``table_name/key_value``. In this case, the ``_from`` and ``_to`` attributes could be ``members/1`` and ``clubs/1`` respectively, which would indicate that the member with _key value of 1 in the ``members`` table is a member of the club with a _key value of 1. As another example, the John Adams row has a _key value of ``7``; his node ID is therefore ``members/7``. You can think of the rows of such a table as a directed links connecting two of the nodes from somewhere in the workspace. To see this in action, download :download:`membership.csv `, and upload it as a table. Because this table has properly formatted ``_from`` and ``_to`` attributes, Multinet recognizes it as an *edge table*. If you click on the newly uploaded table, you can explore what the rows look like. Note that while edge tables can also have other attributes, this one does not. **4. Create a Network** Creating a network in Multinet is a matter of specifying an edge table that defines that network's topology and implicitly (via the ``_from`` and ``_to`` values of its edge table rows, the nodes involved as) its nodes as well. To create the Paul Revere network, click on the plus icon to the right of the Networks column. When the dialog box appears, click on the ``CREATE`` tab at the top, then select the ``membership`` table from the dropdown. Note that Multinet already knows which tables are edge tables, due to the presence of ``_from`` and ``_to`` attributes. Fill in the name of the network with ``boston``, and then click on the ``CREATE NETWORK`` button. You should see the new network appear in the Networks column. If you click on the new network, you will be taken to the network view, which aggregates various pieces of information about this network, and provides links to visualization applications. Note that the main panel displays some characteristic information such as the number of nodes and edges, and the drawer at the bottom displays information about the node types comprising this network, the edge table that provides the connectivity, and a paged view of the nodes themselves, identified by their node IDs. Clicking on these items will bring you to dedicated views providing specific information; you can return to the network view using the browser back button. **5. Visualize the Network** Now that the Paul Revere network is known to Multinet, its component data is now available via the Multinet API to be consumed by different analysis and visualization applications. To demonstrate, we will launch an interactive node-link diagram to see what this particular network looks like. In the network view, note that the right-hand sidebar contains a list of external applications it can open. Click on ``Nodelink`` to open the node-link diagram in a new tab. This application works by sending REST requests for the specified network to the Multinet API server (which is the same server that provides the file-browser-like view of the data that we have been learning about in the Multinet client). As data about the nodes and links arrives in this application, it can construct an interactive visual model of the network as a collection of physical nodes connected by physically springlike links. Play with the network in this application and explore the various options available in the control panel.