NICHEWRK(1)

NAME

SYNOPSIS

	nichewrk [ -L	positions ] [ -I configuration ] 
	[ -S percent ] [ -title string ] nodes links [ data1 data2 ... ]

AVAILABILITY

DESCRIPTION

OVERVIEW

You can directly manipulate the NicheWorks display. Using the mouse, you can interactively explore the network by focusing on a node, zooming in or out, and panning around the network. Link and node size may be changed, as well as shape and color.

NicheWorks models data as a set of nodes and links between the nodes which have data. The nodes may be of different type (distinguished by a data characteristic), but only a single link may be used. Any type of graph may be used, including one containing unconnected nodes. Any number of characteristics may be available for the nodes and the links. The user can select any of the link statistics to use in controlling the layout of the network on the display. Nodes that have "high" values of the link statistic will be placed near each other; links with "low" values will be separated. This visually displays node relationships based on the statistic. Other node and link statistics may be mapped onto visual characteristics of the display, such as color, size, and shape.

A standard scenario for using NicheWorks is to first acquire the data and perform any data conditioning (e.g., square rooting counts, accumulating totals) to produce the input data files (described below) through the use of the data manipulation tools of your choice (e.g., SQL, AWK, FIT, SED, Basic, etc.). Invoke NicheWorks. Choose a link as the placement weight, and perform placement. When you are satisfied with placement, map other data statistics onto the visual display characteristics. Use histograms to filter the data to concentrate on ranges of interest to you. Use the detail window to focus on the relationships of a particular node. Iterate as desired.

OPTIONS

• -L position
  A file containing position information for drawing the network display. Positioning is done within Niche- Works, and once a good layout is found, the layout may be saved to avoid repeating positioning during a subse- quent session. (Positioning is saved with the "Operations->Save Position" menu bar item.) If no position file is given, a default positioning will be used.
• -I configuration
  A file containing initial configuration information to associate data with node and link attributes. If this option is not given, the program will look for a default configuration file, nichewrk.cfg, and if that is not present either, no data will be associated with the node and link attributes initially. A configura- tion file can be created from within NicheWorks using the "Operations->Save Configuration" menu item.
• -S percent
  The initial scaling to be used for links and nodes. The default is 100%; the value given can be between 0 and 200.
• -title string
  Use string as the window title. The default is the first word on the command line.
• nodes
  A file that contains the names of the nodes, one per line.
• links
  A file that defines the links between nodes.. Each line of the file represents a directed link in the net- work and consists of the names of the originating and terminal nodes (as defined in the nodes file), separated by tab.
• data1 data2 ...
  These optional arguments each represent a set of data values to associate with links or nodes. Whether the data is for links or nodes is determined by the number of values in the file: it should match either the number of links or number of nodes (and there had better be a different number of links than nodes). If the first line starts with '#', it is taken as the title of the data; the title defaults to the file name otherwise.

EXAMPLE 1

starts NicheWorks using data describing local telephone exchange calling. The names file contains the phone numbers, for example:

          32241520
          32242219
          32242716
          32243207
           ...

          32650137	  39214812
          32650151	  32542100
          32650171	  37269885
          32650173	  34732210
          32650320	  34895588
           ...

The position file describes the initial position of the nodes in the display; it was saved from NicheWorks in a previous session.

The connect file is a link statistic, the connect time for each phone call:

          # Call Connect Time
          5.51342874616498
          4.98360662170834
          8.08641027532378
          5.94542060860658
          4.90527477843843
           ...

          # Number of Calls
          1
          2
          1
          1
          1
          1
          1
           ...

          # Zip	Code
          6132
          6132
          6132
          6132
          6132
          6132

EXAMPLE 2

This sample data is for looking at affinities between fruits. The command line used is:

               nichewrk	items pairs quantity affinity

          WHAT:	       (nodes)	    (links)	  (node		(link
                                                 attribute)   attribute)
          FILE NAME:	items	     pairs	  quantity     affinity
             ^
             |		apple	  apples banana	     5		 .75
          CONTENTS	banana	  apples cherry	     12		 .45
             |		cherry	  banana cherry	     7		 .25
             |		pear	  banana pear	     9		 .63
             |		peach	  banana peach	     4		 .33
             |			  cherry peach			 .23
             v			  pear	 peach			 .66

EXTENDED DESCRIPTION

• a menu bar,
• a control panel, and
• a network display region.

MENU BAR

• Operations
  provides general operations.
  Find pops up a dialogue into which a specific node name may be typed, and that will be made the current focus node. Regular expressions may be used in names.
  Detail pops up a new window that shows the focus node and its adjacent nodes.
  Print produces a post script dump of the display.
  Screen Dump produces an X-windows dump of the display.
  Screen Undump allows you to view an X-windows dump of the display.
  Save Position, if available on your installation, saves the current node layout in a file.
  Save Configuration saves the current attribute assign- ments in a file.
  Quit terminates the program.
• Positioning
  if available on your installation, can be used to start or stop node layout, and control the way in which lay- out is being performed. All placement options continue iterating until they are explicitly stopped by the user by choosing "None". The Size statistic in the Links section of the control panel is the statistic that drives placement: nodes linked with high values of this statistic are positioned close, nodes linked with low values are separated. Options are:
  None turns off positioning.
  Swap changes the layout by swapping nodes and evaluat- ing if the swap improves the layout by making closely- coupled nodes closer.
  Move changes the layout by moving nodes and evaluating if the swap improves the layout by making closely- coupled nodes closer.
  Apart moves nodes further apart. Since positioning tries to move H4ly-coupled nodes close together, the result may be a cluster where the nodes are "too close", so they are difficult to distinguish. This spreads the nodes further apart.
• Zoom
  is used to zoom in or out around the center of the display. Zooming can also be done using keyboard keys or the mouse (see below).
  Zoom In magnifies the image.
  Zoom Out reduces the image.
  Fit redraws the display at full scale to fit the draw- ing area.
• Options
  Colors allows the choice of a rainbow, pastel, or gray scale color scheme.
  Directed controls whether links are displayed as arrows to denote the direction of the link. The beginning of the arrow is the first node defined for the link.
  Labels controls whether nodes should always be labeled.
  Graphics Buffering controls whether buffering should be used so that the display update happens all at once rather than as the screen is redrawn. On slow machines, graphics buffering may be turned off so that the user knows that some- thing is happening.
• Filters
  created a histogram in a new windows of the distribu- tion of the values for a single statistic. This is described in more detail below.
  Generations allows the main display to be filtered to show only nodes reachable from the current focus node by that many steps. Exit this filtering using Undo, described below.
  Undo backs out the last filtering operation requested by the user.
• Bookmarks
  saves or restores the state of NicheWorks so that it may be returned to. Bookmarks are retained on disk, so they persist between sessions.
  Goto ... creates a dialogue that may be used to select an existing bookmark to reinstate.
  Create ... creates a dialogue that may be used to name and create a new bookmark.
  Delete ... creates a dialogue that may be used to delete an existing bookmark.
• Help
  gives access to assistance. Types of assistance that are not available in the current installation will be grayed out.
  On Context provides context sensitive help: the cursor changes to a question icon, and clicking on the Niche- Works user interface requests a description of the interface object clicked on.
  On Help describes how to use the help system.
  On Window describes the use of the window containing the menu bar.
  Man Page provides this manual page in a scrolling text window.
  Index provides an index of the help available.
  Tutorial provides a tutorial.
  On Version provides the version of NicheWorks that you are currently running.
  Release Notes provides notes on the current release of NicheWorks, including any known bugs, work arounds, and contacts.
  Script provides a script for running NicheWorks against a sample dataset demonstrating the program capabili- ties.
  Print Manual prints the complete manual; you will be prompted for how to print.
  Online Manual provides the on-line version of the manual.

CONTROL PANEL

Both the Links and Nodes sections allow the statistics to map to color, style, labels, and size to be selected. There is also a slider that controls the relative size of the nodes or links in the network display.

NETWORK DISPLAY

Node Selection
A node may be selected with mouse button 1; the label of the node is shown in the network display and the values for all statistics for that node are shown in the Control Panel. The text displayed is controlled by the "Labels" selection in the "Nodes" section of the control panel. Selecting with mouse button 2 (X/Motif, Control-right button on PCs) displays the label for the node and leaves it on until it is turned off by selection with mouse button 2 again. All text can be turned on using "Options->Labels On".

Zoom/Pan
Your perspective on the network display can be changed by panning the display (moving the contents) or zooming (magnifying/reducing).

Panning can be done with the keyboard arrow keys or with the mouse. With the mouse, hold the right mouse button down and drag to pan the display. The "Home" keyboard button or the menu item "Zoom->Home" returns the display to its starting location.

Zooming can done with menu items, the keyboard, or the mouse. Menu items "Zoom->Zoom In" and "Zoom->Zoom Out" zoom in or out around the current center of the network display. The keyboard keys "PgUp" corresponds to "Zoom In", and "PgDn" corresponds to "Zoom Out". "Home" or "Zoom->Home" returns to the original magnification, showing the entire display. Zooming with the mouse is done by holding down the right mouse button and the keyboard SHIFT key, and dragging up (zoom in) or down (zoom out).

Panning and zooming can be intermixed when using the mouse, since pressing the SHIFT key activates zooming, otherwise panning is done.

FILTERS

The slider at the bottom of the window controls the smoothing of the distribution: more smoothing removes irregular values and makes the distribution more "statistically accurate".

The histogram may be swept with the mouse to "turn off" portions of the statistic, to focus on particular ranges of values. The right mouse button turns off, the left mouse button turns on. Specific values can be typed in to the text entry lines labeled "End Point 1" and "2" to explicitly define the range to be turned off ("Cut") or turned on ("Paste"). The value at the current location of the mouse while it is over the histogram is showed as "End Point 1".

Any number of filters may be created, and they are all linked: filtering in one "turns off" the same values in other filters, so you can see the impact of turning off values from a particular range on the distribution of other statistics as well. possible pair of nodes is connected by a link.

DETAIL

CAVEATS

FILES

          VzBookMarks	 directory containing bookmarks
          nichewrk.cfg	 default configuration file