Configuration

In addition to the previously mentioned options, netshape will optionally and automatically load a netshape_conf.py file in the directory where netshape is being run. This file allows a user to write custom functions for computing network properties, add additional subcommands, or modify existing ones.

The netshape_conf.py file

The netshape_conf.py is simply a python module that is imported before the command line arguments are parsed. This allows this module to define additional command line arguments or change the meaning of existing ones before they are used to build the network visualization.

The conf object

Every netshape_conf.py imports a global conf object from the netshape.config module that is shared across the netshape application. conf object maintains and exposes the configuration state using an internal dictionary of Command objects, each of which represents a single subcommand of the application. This dictionary can be accessed as the commands property of the conf object. Command‘s are indexed by the name of the command itself (e.g. for netshape build, it would be conf.commands["build"]).

The conf object also exposes a method to add commands to the application. This could be useful if a user wanted to make different visualizations of the same network, or required other side effects, like outputting node properties in csv format. This function is accessed via conf.register_command(), and accepts a required command_name argument, as well as optional help which is a string representing the help message for that subcommand, and command_args, a list of dicts of arguments to be passed to the argparse module’s add_argument function, as well as the additional ‘name’ key, which specifies the list of possible names for that parameter.

This enables us to build custom command line arguments which can be used gracefully in the network visualization pipeline.

The Command class

The command class allows us to construct and modify visualization pipelines that serve a common purpose. Currently it is somewhat underdeveloped, and as such, only exposes two methods: Command.read_edges(), which builds builds the original network or adds edges to an existing one. It accepts a single parameter, which is the name of the command line argument that was used to capture the edgelist file. The other method, :code:`Command.add_node_prop`() can be used to add a property to the network. It accepts a name for the property as it’s first argument, a function as it’s second argument, which has some restrictions on it’s arguments, and, additional args and kwargs to pass to that function when it is being called. The function must receive a netshape object as it’s first argument, the name of the property being added as the second, and a dictionary of command line arguments as the third argument. This function then can compute a network statistic, and call,

Netshape.add_node_prop() to add it to the netshape object. These methods are added in order, and executed sequentially to compute all desired network statistics. Then, internal methods are used to build the directory for the web page.

A sample netshape_conf.py

In order to reduce the potential confusion of the above examples, we give an example of a netshape_conf.py file which would result in the default commands. The node_props module adds utility functions that compute various node properties of the network, according to the function format described above. For more details on specific functions, see the Full API

import argparse
import sys

from netshape.config import conf
from netshape import node_props

(conf
 .register_command('build', help="build a static visualization of a network",
                   command_args=build_args)
 .read_edges('network')
 .add_node_prop('Eigenvector Centrality', node_props.eigenvector_centrality)
 .add_node_prop('Community', node_props.modularity_community)
 .add_node_prop('Degree', node_props.degree)
)
(conf
 .register_command('serve', help="utility function to view a network visualization", command_args=[{
        "name": ['-p', '--port'],
        "dest": 'p',
        "default":8000,
        "help": "The port to serve on."
  }])
 .add_node_prop('', serve)

 build_args = [{
              'name': ['network'],
              'nargs': "?",
              'help':"the network, formatted as a csv edgelist - "
                     "accepts a path or from stdin",
              "type":argparse.FileType('r'),
              "default":sys.stdin
          }, {
              "name": ['-s', '--seps'],
              "dest": 'sep',
              "default":",",
              "help": "the string delimiter between values in the edgelist"
                      " (default: \",\")"
          }, {
              "name": ['-d', '--directed'],
              "dest": 'directed',
              "default":"True",
              "help": "Boolean indicator that is True if the network is directed, "
                      "and False otherwise (default: True)"
          }, {
              "name": ['-o', '--out'],
              "dest": 'out',
              "default":"dist",
              "help": "The name of the file to build the web visualization in "
                      "(default: \"dist\")"
          }, {
              "name": ['-n', '--name'],
              "dest": 'name',
              "default":"Network",
              "help": "The name of the file to build the web visualization in "
                      "(default: \"Network\")"
          }]