Getting started

Running GraphTerm

To install GraphTerm, you need to have Python 2.6+ and the Bash shell on your Mac/Linux/Unix computer. For a quick install, use one of the following two options:

sudo pip install graphterm
     OR
sudo easy_install graphterm; sudo gterm_setup

Omit the sudo if you are installing as a non-root user within an Anaconda or Enthought Python environment, for example. (See the Installation section of the README file for additional installation options, including source installs.)

To start the GraphTerm server, use the command:

gtermserver --terminal --auth_type=none

This will run the server and open a GraphTerm terminal window using the default browser. For multi-user computers, omit the --auth_type=none option when starting the server, and enter the authentication code stored in the file ~/.graphterm/_gterm_auth.txt as needed.

You can access the GraphTerm server using any browser that supports websockets. Google Chrome works best, but Firefox, Safari, or IE10 are also supported. Start by entering the following URL:

http://localhost:8900

In the graphterm browser page, select the GraphTerm host you wish to connect to and create a new terminal session. (Note: The GraphTerm host is different from the network hostname for the server.) Within a GraphTerm window, you can use terminal/new menu option to create a new GraphTerm session.

You can also open additional GraphTerm terminal windows using the gterm command:

gterm --noauth [session_name]
gterm -u ubuntu --browser="Google Chrome" https://example.com:8900

where the terminal session name argument is optional. (This command can automatically process authentication codes from your ~/.graphterm directory.)

Type gtermserver -h to view all options for starting the server. You can use the --daemon=start option to run the server in the background. The --host=hostname option is useful for listening on a public IP address instead of the default localhost. The --auth_type=none no authentication mode is useful for teaching or demonstration purposes, or on a single-user lapttop/desktop, where security is not important. Another useful no authentication mode is --auth_type=name which enables simple name-based sharing. (For more on running publicly accessible GraphTerm servers, see Setting up a Virtual Computer Lab.)

Within the terminal, try out the following commands:

hello_gterm.sh
gls <directory>
gvi <text-filename>

The gls and gvi commands in the GraphTerm toolchain imitate basic features of the standard ls and vi commands (see GraphTerm toolchain and features). (Note: You need to execute the gterm_setup command to be able to use the GraphTerm toolchain. Otherwise, you will encounter a Permission denied error.) To display images as thumbnails, use the gls -i ... command. Use the -h option to display help information for these commands, and read the tutorial Using the graphical features of GraphTerm for usage examples.

If you wish to use GraphTerm to set up up a virtual computer lab for multiple users, see the section Setting up a Virtual Computer Lab. To use GraphTerm features on remote systems and via SSH, see Remote access and SSH.

iPad/Android tablet usage

GraphTerm can be used on touch devices (phones/tablets), with some limitations. Use the view/footer menu to enter keyboard input, send special characters, access arrow keys etc. Tap the Kbrd in the footer to display the keyboard. (The Footer menu display can also be toggled by clicking on the last displayed prompt.)

Note: You should turn off the Autocapitalize and Autocorrect features in the language/keyboard settings if you plan to do a lot of typing on touch devices.

Inline graphics and notebook mode

GraphTerm supports inline graphics display with matplotlib and pandas Python packages (see below) and also with R (see Using GraphTerm with R). It also supports a lightweight notebook interface.

Inline plots using matplotlib

Assuming you have matplotlib installed, the gpylab module in the $GTERM_DIR/bin directory can be used to start up the python interpreter in pylab mode for inline graphics within the GraphTerm terminal:

python -i $GTERM_DIR/bin/gpylab.py
>>> plot([1,2,4])
>>> plot([1,3,9])     # Overplot
>>> figure()          # Clear figure
>>> plot([1,3,9])
>>> newfig()          # New figure
>>> plot([1,4,12])

Inline graphics also works with the ipython command in a similar manner. Instead of typing the long python command line above, you can use the shortcut commands gpython or gipython, e.g.:

gpython
>>> plot([1,2], [3,6])
https://github.com/mitotic/graphterm/raw/master/doc-images/gt-inline-plot.png

Run $GTERM_DIR/bin/gmatplot.py for a demo of inline graphics (see Simple inline animation using matplotlib). See the function main in this file for sample plotting code.

  • Use figure(...) to clear current image
  • Use newfig(...) to create blank image
  • Use resize_newfig(...) to create resize blank image
  • Use show() to update image
  • Use show(False) to display as new image
  • Use display(fig) to display figure
  • Use ioff() to disable interactive mode
  • Use gterm.nbmode(False) to re-enable default expression printing behaviour

Inline tables using pandas

GraphTerm can display pandas DataFrame objects as a table using HTML:

gpython
>>> import pandas as pd
>>> d = {'one' : [1., 2., 3., 4.],
>>> 'two' : [4., 3., 2., 1.]}
>>> pd.DataFrame(d)
https://github.com/mitotic/graphterm/raw/master/doc-images/gt-pandas.png

Notebook mode

GraphTerm supports a notebook mode, where code can be entered in multiple cells and executed separately in each cell to display the output (see GraphTerm Notebook mode running Python). Currently, the notebook mode can be used with the shell (bash), or while running python (python/ipython) and R interpreters (see Using GraphTerm with R). You can create new notebooks using the notebook/new menu option and then selecting the language.

You can try using the notebook mode with any other shell-like program (such as IDL or ncl) which has a unique prompt by typing Shift-Enter after starting the program. Type Control-Enter instead, if you wish to read a notebook file and/or customize the interpreter prompts. Alternatively, you can select notebook/new/default menu option after starting the program (this works even with the bash shell!).

To open an existing notebook, use the gls command to list your notebooks, e,g.:

gls *.ipynb

Then click on the notebook that you wish to open. Alternatively, you can use the gpython or gopen commands python notebooks:

gpython notebook.ipynb

For other languages, you will need to start the interpreter and then use the notebook/open menu option.

https://github.com/mitotic/graphterm/raw/master/doc-images/gt-nb.png

Within notebook mode, type either Control-Enter to execute code in-place, or Shift-Enter to execute and move to the next cell (creating a new cell, if necessary). You can also use the run button on the top menu, which behaves like Shift-Enter but does not create new cells. Other notebook operations can be carried out using the notebook menu or the keyboard shortcuts listed under help/notebook shortcuts.

Notebook cells can also contain descriptive text in Markdown format. The notebook/markdown menu option can be used to toggle a cell between code and Markdown mode and double-clicking on the rendered text displays the editable Markdown cell.

The notebook/save menu option can be used to save notebooks either in the IPython Notebook format (*.ipynb) or in the Markdown notebook format (*.py.gnb.md). The filename determines which format is used. You can exit the notebook mode using notebook/quit in the top menu bar, or by typing Control-C, to return to the terminal mode.

Sharing and security

Terminal sessions and “screensharing”

For each host, terminal sessions are assigned default names like tty1, tty2 etc. You can also create unique terminal session names simply by using it in an URL, e.g.:

http://localhost:8900/local/mysession

The first user to create a session “owns” it, and can make the session publicly available by disabling the share/private menubar option. The public session URL can then be shared with other users connected to the same GraphTerm server, to provide read-only access to the terminal. (This is like “screensharing”, but more efficient, because only the content is shared, not the theme/style data.)

If the session owner has unlocked the session by disabling the share/lock menubar option, other users can also steal control of the session using the menubar button (or using the share/control menu item).

For example, if you forgot to detach your session at work, you can ssh to your desktop from home, use SSH port forwarding to securely access your work desktop, and then steal the session using your home browser (see Remote access and SSH).

Normally, only a single user has control of a terminal session at a time. There is a share/tandem option that can be enabled to allow multiple users to control the terminal session at the same time. However, this could sometimes have unpredictable effects.

Security

You should normally run GraphTerm logged in as a regular user, using the default --auth_type=singleuser option, which requires an access code for HMAC authentication. Using the gterm command to create a new terminal provides convenience and additional security, as the command validates the server and handles authentication before opening a new terminal. On a single user computer, such as a laptop, the --auth_type=none option, with no access code, can be used instead.

Although GraphTerm can be run as a public server, this feature is best used for teaching and demonstration purposes. In this case, the --auth_type=name option can be used, if all users can share an account, with no access code. The --auth_type=multiuser option, which requires the server to run with root privileges, is suitable for a multiple user lab setting, providing a choice of either access code HMAC authentication or Google Authentication. The --auth_type=login option, which is permitted only with a localhost server or with HTTPS, implements the standard password login. The --nolocal option can be used to disable root access via the browser. The HTTPS protocol can be enabled for the public server, using either self-signed or authoritative certificates, to provide additional security. (See see Setting up a Virtual Computer Lab for more on authentication options.)

When working with sensitive information, it would be best to run the server on localhost (the default) and use SSH port forwarding to connect to it from other computers as needed (see Remote access and SSH).