Graphic exploration of statistical and geometric properties of sets of tables.

SUMMARY
-------

* Panel [Property/Selection of Tags]:
Creates a working selection, a subset of particle tags.

* Panel [Plot Options]
- Depicts the selected particles according to their table poperties.
- Compares the behaviour of different tables.

* Panel [Tables]
- Enter tables into memory.
- Save restricted versions of the contained tables.

* Panel [Scene]
- Send the graphical output to differen windows (0 is window in tableview)
- (de)activates the automatic graphic echoing of selection operations.

* Panel [Data]
Shows volumetric depictions of selected particles.

SELECTION OF TAGS
-----------------

The main goal of this GUI is the construction of subsets of tags
(i.e. particles) according to their properties reflected in the table.

This is driven by the [Properties / Tag selection] Panel:

* Depiction area
In the left part you select which properties from the table will be
inspected and posssibly used as restriction criterion.
Each column in this area signals how and if a property will be
depicted. The specific depiction style is dependent on the Viewing
option, defined in the left bottom of the Panel, and explained below.

Properties "tag number", "tilt" and "CC" and hard coded in the first
three rows. The other rows can show table properties selected by the
user, by typing in the corresponding column number.
The question mark "?" prints the standard Dynamo convention for the
content of the table columns.

* Selection area
In the right part of the Panel, you can construct subset of tags,
according to the values of the table property selected in the
correspondig row.

The final working selection of tags is the intersection of all
defined selections.

[select subset]:
In these edition fields you can input an interval of values
on the selected property, of pass directly a set of selected
values.

Valid syntaxes:
* to select a range of values:
A,>A.
* To select a discrete set:
use any Matlab indexing forms (as A,B,C,D, A:D...)

[view]: shows an histogram of the property, allowing the
selection on screen of intervals of interest.
The selected interval will be copied to the [select range]
field.

(x): Exclude selection.
If the radiobutton (x) is switched on for a property, the
values in the [select subset] interval are interpreted
as range or set ov values to excluded.

Other controls are available to operate on the selection.

SELECTION OF TABLES
-------------------

When comparing the properties of several tables, you need to define
one of them as the the "reference" one (with the [main table] control).

Additionally, in the [Manage tables] button you can open a manager that
keeps track of the tables currently in memory. You can perform there simple
table operations (restrictions, comparisons, merging...)

DEPICTION
---------

Different viewers for the behaviour of the selected property(ies)
across the data set are available.

The Panel [Plot Options] shows properties common to al viewing styles.
In all cases you can restrict the depiction to the selected set of tags,
(radiobutton "depict only_selection" on), to all tags, or to all tags but marking the selected subsets.

* Plot
----
Plots the selected properties on the selected tags.

* Scatter
-------
Scatter plot of two or three selected column properties.
It is important to control the [Scatter Plot] option Panel, as
this viewing type reads there which classes/subreferences
are depicted.
A frequent issue is the apparent failure of tableview to recognize
all the table entries: this happens when you are using the default
settings, which point only to a single class. See below for options
to tune his behaviour.

[show classes] : leave empty to get global depictions of all the
particles.
[classes in column]
: normally, "classes" are recorded in column 22 of a
table. This is the default value.
However, it is frequently useful to group particles
in terms of their membership into sets defined in
some other column of the table. You can use this
edit field to instruct tableview to use a different
column in this context.
Typical choices are:
20 "Tomogram number"
34 "reference"
35 "subreference"
37 "defocus"

Note that the [Depicted Properties] Panel, in this context, opens the
option of colouring and labelling points in terms of the class
membership defined here.

* Sketch 3d
---------
Sketches the 3d orientation of the particles.
The default functionality depicts each particle as three semiaxis. The
relative length can be controlled with the [x],[y] and [z] controls
in the [Extended Options for 3D Sketch] panel).

[which tomograms] : it is a key field in this context, as one is
frequently interested in displaying in a single
plot only those particles steming from a given
subtomogram.
If switched on, the column 20 of the table will
be interrogated for the originary tomogram of
each particle.

(real 3d positions): if switched off, particles will be distributed
on a 2d grid, showing only the real orientations.
This modus allows the simultaneous
representation of particles from different
tomograms.
If switched, the 3d locations and shifts of the
particles will be read from their expected table
positions (24 to 26).

* Placing density volumes.
In this Panel, it is possible to use the table to visualize the
3d positions and orientations of the copies of a template by
actually placing and isosurface representation of each copy.
[Isolevels] : isolevels of the template to include in the
depiction
[ - ] : invert the intensity map.
[ Matlab ] : creates the depiction with the native Matlab tools
for isosurface depcition.
Normally, this is only useful for small depictions.
[ Chimera ] : creates a Chimera .cmd file that generates the
placing scene.

* Histogram
---------
Simple histogram representation on the selected properties.
Vertical dimension (bar height) represents particle count.
3d histograms

* Spherical histogram
-------------------
A kind of representation useful to exhibit the behaviour of table
properties of the particles in conexion with their orientation.
The "property viewers" are differente ways to represent a property
in this context. Each one is indicated in a column of the [Property]
Panel. It the radiobutton that intersects a column (a "viewer") and
a row ( a "table property") is switched on the property will be
represented as:
- face color : the sphere surface is divided in sectors
which are coloured according to the average
value of the property for all particles
pointing in this orientation.
- radius length :
- radius color :
- point color : points representing particles/classes
on the sphere surface are coloured
following a color scale.
- text label : the numerical value is printed close to the
particle/class label.

Some specific controls for this option:
(active) : Not all the property viewers need to be active.

(mean on region) : if switched on, the property is depicted
in terms of its averaged value from all
the particles contributing to a given
orientation.
Otherwise, the information relative
to each particle will be depicted
[Spherical Sampling]: controls the size of the regions.

DATA
----

The [Data] Panel allows to visualize quickly some particle or set of
particles, and how they transform under the currently active table.

TABLES
------

Enter tables into the internal memory of tableview. They can be
accessed by the manager in [table manager]
[Project] : Enters all the "refined_table" items found
in the porject.
(Append) : The indicated tables will be added into the manager,
otherwise they will replace the current contents.
[Export] : restricts the current table to the selected tags
and writes the result into a file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

COMMAND LINE SYNTAX

INPUT

Input runs completely on Parameter/Value couples.

a) Basic parameters

Used to work with tables defined independently from a database.

'table' - char (for files)
- numeric (for tables defined in the command line)
- cell (to pass lists of tables -both as filenames or numeric- )

'table_label' A string that can be passed to identify the
table in the depictions
- char (to label a single table)
- cell (to pass labels for a multiple input)

'project_label' An additional string that can be passed to
identify the project to which the table belong
- char (to identify a single project for all
tables that have been passed)
- cell (to specify different projects on different
cells)

'folder_data' (Not frequently required)
Allows to link a data folder. With this option,
tableview will understand that the particle tags
in the table are synchronized with the particle
tags in the data source you specifified.
Values for 'folder_data' can be passed as:
- the name of a Dynamo data folder.
- a .sel file (Spider-style selection file)
- a regular expression comprising a '*'
character.

'template' (Not frequently required)
Allows to link a single volume to tableview. Some
output options will apply the spacial transformations
determined by the table on this map. This rends a very visual
depiction of the alignment results, specially if
the 3d coordiantes of the object in the cell are
available in the data.

b) Database parameters

It is normally more comfortable to ask tableview to query a database to retrieve
an item or a set of items.

'project' The presence of this parameter states that input
will located in the database of a project(or
several ones). The passed value identifies the
project.
Possible value types are:
- char: to identify a project database by its name
- vpr: to refer to the database contained in
the virtual project.
- cell: to pass multiple databases

'ite' Which iterations will be passed
'*' character is admitted to refer to all
iterations.

'ref' Which references will be passed
'*' character is admitted to refer to all
references.

'type' which kind of table among all the table filetypes
managed in the database you are interested into.
Possibilities are:
- 'refined' The most frequently used option: the
result of an iteration.
For convenience, 'ite'=0 will produce the starting
seed(s) of the procedure, so that
you can scan the convergence
process.
- 'starting' The seed(s) of a single iterarion.
- 'input' The seed(s) of the whole alignment
procedure as it is stored in the database .
- 'linked' The file(s) that was linked into the
database. It should be the same as
the 'input' option.

* default: 'refined'

c) Training parameters

'random' Generates a random table. Valid values are:
- scalar: number of randomly generated particles.