Quickstart

MIEN can be used in several ways. This page describes getting started with MIEN's built in graphical interfaces. If you are interested in using MIEN as a programming library, or using the MIEN command line interface, look here, and if you would like to modify or extend the MIEN interfaces, look at writing extensions.

Getting MIEN

If you don't have MIEN installed yet, check out one of these documents for install instructions:

• Quick Intsall if you want to get MIEN running as fast as possible

• Source Intsall if you want the most flexible and maintainable install, if you are a Python developer, or if you have a highly customized Python install on your machine already.

Launching MIEN

The best way to run MIEN is to launch the mien GUIs from a terminal, using the mien command (Do I really HAVE to use a terminal?, How do I use a terminal? ). If you installed MIEN using a deb package, or Mac installer, a copy of this command should have been placed somewhere in your system PATH. You can test this by typing mien --version into any terminal. If this prints a bunch of version information, starting with Python version, then things are set up correctly. If you see something like -bash: mien: command not found, you will need to find the mien command. If you get some other sort of error, including any Python errors beginning with the word Traceback and ending with something like ImportError: No module named mien.tools.identifiers, then you probably need to set up your Python path.

Provided the mien command is working, you can now launch the primary mien GUI apps using it. Just entering mien alone launches the XML Editor. To launch other applications, use the following variants of the command:

mien -a data launches the DataViewer (for time series numerical data)

mien -a image launches the ImageViewer (for 2D image files and image stacks)

mien -a cell launches the CellViewer (for 3D anatomical and spatial data).

In addition to launching the apps, you can include the names of data files to open on the command line. MIEN will open all the files named on the command line and concatenate their contents into a single document, which is then passed to the requested application. For example:

mien -a cell *.asc will open all of the files in the current directory with extension .asc in the CellViewer.

mien -v name_of_file will attempt to guess the type of data in the file "name_of_file" and open it in the appropriate viewer.

These examples are sufficient to open and use the most common GUIs. To do more complex jobs with the mien command, try looking at the mien command help, or if you are comfortable with Unix-style man pages, use mien -h to print the command documentation.

Many users would prefer the DataViewer to be named dv, rather than mien -a data. If you would rather do less typing, that can be easily arranged using the alias command, as described here.

What do these GUIs Do?

MIEN has a lot of component GUI apps. In this document we will talk about the XML Editor, DataViewer, CellViewer, and ImageViewer. There are a number of other GUIs which operate as extensions to the XML editor for working with particular object types, such as abstract models, cell models, and optimizers. Use of these GUIs is a more advanced topic, not included in this document.

The different GUIs specialize in displaying different types of data. They also provide access to processing functions particular to a given type of data. With the exception of the XML editor, each GUI will only display data of it's particular type, so it will only show a subset of a document containing many types of object, and it might show nothing, if all the objects it the document are of a different type.

Each of the main GUIs is described in a separate section below.

• The XML Editor: Useful for examining any type of data, editing metadata, checking, or changing the precise values of attributes, adding new components to a model, and coordinating data between the other GUIs when working with a model that contains several data types

• The Cell Viewer: Useful for dealing with anatomical data, or with statistical or image data that are associated to locations in 3D space. The Cell Viewer can also be used to select and edit components of a compartmental cell model, and to visualize properties of these models as a function of location.

• The Data Viewer: Useful for viewing and analyzing numerical data, particularly time-series data and event sequences, such as those generated by electro-physiology recordings.

• The Image Viewer: Useful for viewing and editing images, image stacks, and video sequences.

Getting and Loading Data

In order to make the MIEN GUIs do anything interesting, you will need to load some data.

You can download some example data files from http://mien.msu.montana.edu/repository/testdata/ or http://neurosys.cns.montana.edu/MIEN/index.html.

Here are some other sources of data:

• Images to send to the image editor are easy to come by. MIEN understands many common image formats, such as png, jpeg, and tiff.

• Cell anatomy data can be downloaded in Neurolucida or SWC format from several databases, including http://jazz.msu.montana.edu/publicrecon/cells and http://neuromorpho.org/neuroMorpho/index.jsp

• Cell Viewer can read output written into "ascii" format by Neurolucida version 7.

• If you use a DataMAX data acquisition system, you can import recorded data directly into MIEN's Data Viewer.

• If you use Matlab for data analysis, you can send data to the Data Viewer in a .mat file. Getting the data to load in MIEN is easy (just don't save sparse arrays, and you should be fine), but getting complex data to be correctly identified as the right data type can be harder. For now, try saving a single 2D array of evenly sampled data, with sample number in the rows of the array, and different channels or variables that are sampled in the columns.

• You can store numerical data in text files. Use new lines in the text file to separate samples, and within a line, use spaces to separate different measurements. If you like you can construct a header at the beginning using Key:Value pairs. The most useful thing to put in a header is the sampling rate. Use something like SamplesPerSecond:10000 to set this value. You don't need to use a header at all, though, if you just want Data Viewer to load and plot the data.

• You can open any well formed XML file in the XML editor using mien -p NameOfFile. The "-p" tells mien to be "permissive" of XML dialects other than its own. Many of the neuroscience specific features of MIEN won't work on arbitrary XML, but you can always browse and edit the document structure with the editor.

There are lots of other ways to import data, but these methods should get you started.

XML Editor

The XML editor can be thought of as the top level GUI. In a typical data-integration task, the XML editor is the application to open first, and will stay open throughout the job. It can be used to view the structure of a whole model, and also to send various parts of the model off to more task-specific GUIs for processing (See interaction between guis for examples of running more than one GUI app on the same model at the same time). The strengths of the XML editor are that it can show any type of object, can do a huge variety of model modifications, and provides a very precise view of a model, where, for example, the numerical value "5" appears as a "5" rather than as a line or color. The disadvantage of the XML editor is that it doesn't provide high level visualization or interface functions, so tasks using it can be painstaking and may involve many operations, or viewing long lists of properties. This makes the XML Editor a good control center for a complex set of tasks, but if any of those tasks can be done in a more specialized GUI, you probably want to do them there.

Tutorial for using the XML editor

Cell Viewer

The CellViewer can display 3D graphics and image stacks. Image are sequences of images representing serial 2D sections through a 3D volume. They are typically generated from microscopy experiments. Other common types of 3D data used by MIEN are anatomical reconstructions of cells, anatomical fiducials, and density fields. Fiducials are reconstructions of anatomical landmarks, which may or may not be nerve cells. For example, many of the data used during the development of MIEN were recorded within a particular ganglion in an insect nervous system. The outline of the exterior ganglion membrane is a fiducial marker that can be recorded in many different experiments. It is used to determine the correct spatial relationships between anatomical data sets from these different experiments.

User Manual for the Cell Viewer

Tutorial for using the Cell Viewer

Data Viewer

The Data Viewer handles numerical data, particularly uniformly sampled sequences of measurements in time. In addition, the Data Viewer provides access to the set of DSP (digital signal processing) functions provided by MIEN and by any installed blocks. This makes the Data Viewer a powerful analysis tool as well as a viewer. The DSP Editor GUI, which is not discussed in the introductory documentation, is a better choice for developing complex data analysis tool chains, but the Data Viewer is sufficient for a large number of exploratory analysis tasks.

User Manual for the Data Viewer

Tutorial for using the Data Viewer

Image Viewer

The Image Viewer provides display and simple editing and measurement tools for use with image data. MIEN stores image data internally in essentially the same format as time series data, but it is common to use different types of visualization and different analysis functions on these different forms of numerical data, so different GUIs are provided. The Image Viewer provides an extension architecture similar to the DSP system provided by the Data Viewer, so that image processing algorithms can be quickly added to the GUI. At this time, however, there are many fewer image functions than DSP functions included in MIEN, so the Image Viewer is much less powerful an analysis tool than the Data Viewer, unless you wish to write your own analysis functions.

Tutorial for using the Image Viewer

Running Several GUIs at Once

The GUI applications listed here can each run as a free-standing independent application, but they can also run as a linked group of applications. The XML editor can launch any of the viewer applications, either using selections from the "Extensions" menu, or using the "Send to Viewer" option that appears in the context-sensitive menu when selecting certain types of data. The viewer GUIs can each launch an XML Editor using the "Data Editor" menu command.

When one GUI is launched from another, the behavior of the linked group is different than if you separately launched each GUI from the command line. The main difference is that the linked group shares a single MIEN document, and changes made by one GUI affect the others. It is also possible to propagate user input from one GUI to another, for example selections made on the 2D image of a cell in the Cell Viewer can be sent to the XML Editor, where they are converted to selection of a list of XML tags. These tags can then be grouped or edited in the XML Editor, and the changes will propagate back to the Cell Viewer.

Note that there are several known bugs relating to sharing state between GUIs. In most cases, things work as expected, but sometimes you may need to manually refresh the display in one GUI to show changes made in another.