Model

The model is the standard way to create and store annotations in a tomogram. The most usual application of a model is in particle picking and extraction.

A model has three basic functionalities, applied sequentially:

1. Data input

   Controls how the user feeds data into the model. An appropriate model provides the user with tools to inspect the tomograms, locate manually or semi-automatically regions, structures or coordinates of interest and mark them.

2. Geometrical computation stage.

   Converts the input into particle positions.

3. Archiving the annotations.

   Models are naturally integrated inside the catalogue system, making the process of extracting particles very easy.

For the first two functionalities, Dynamooffers different types of models, adapted to the different geometries that you might encounter: filaments, vesicles, irregularly shaped membranes, isolated particles, pseudo-crystaline arrangements....

Working with models

Input stage

This part represents the interaction with the tomogram. Depending on the model, it might imply directly clicking particles, or clicking centers of vesicles, points on a membrane.

In most models, this stage produces a matrix of points in the field points of the model.

Computation stage

Once the initial points that describe the geometry of interest have been introduces, the user can choose for different parameters that will determine the actual location of the parameters. For instance, for vesicles, the user can choose the separation of particles for an even distribution on the vesicle surface, for filaments the user can chose the distance along the axis between successive cropping points. This process ranges between the trivial (isolated particles without preassigned orientation) to more complex construction (particles evenly distributed on arbitrarily shaped membranes)

At the end of this stage, all models will contain (non empty) fields crop_points and crop_angles. Dynamo will use them internally if you crop particles with the catalogue (useful when several models and tomograms are present), or you can extract a single cropping table corresponding to this particular model

>> t = myModel.grepTable();

Basic operations with models

Model files and model objects

A model file is simply a file containing a model. A model object is a model as seen in a current Matlab or Dynamo Standalone session. The model object is, so to speak, an "alive" entity that is brought to the RAM for edition and work. With the order

>> m = dread('myModel.omd');

we are reading the contents of the file myModel.omd) and bringing it into memory as the variable arbitrarily named m in the current session. We can edit this variable and write it back to disk when we are done, to the same or to another file, for instance with.

>> dwrite(m,'someOtherModelFile.omd');

Technical information

A model object has always a superclass of type model, and the class will depend on the particular geometry.

Types of models

There are different model classes. A model class is indicated in fixed width, and defines completely the two functionality stages of a model. We talk loosely about "membrane models" or "filament models", but to refer precisely to the a model with a given set of functionalities, we need to name the class. filamentWithTorsion and filamentRings are two classes of filament models, and membraneByLevels is the class normally used for defining Membrane models freely shaped membranes.

Technical information Model classes are defined inside the Dynamo package dmodels

Isolated particles

In those modes, #computation stage is trivial. User points are directly mapped into crop points. Optionally, one common orientation can be selected for the full set of particles in the model

Filaments

Main article: Filament models

Adequate for particles evenly distributed along filaments. Subomograms can be defined to include full sections of the filament (with an initial orientation coaxial with the filament) or to be defined as centered in the building subunits and with an initial direction orthogonal to the axis. Filament models can also be used as support geometry for particles the decorate the filaments irregularly.

Membranes

Main article: Membrane models

When particles are regularly distributed on a membrane (or a membrane fraction) that cannot be approximated by a vesicle.

Vesicles

Main article: Vesicle models

Adequate for particles evenly distributed on spheres or ellipsoids.

Archiving models

After creating or working with a model, it is important to remember to save it into disk. This will save the model in an appropriate place of the catalogue folder, and also create some internal links inside the catalogue.

Importing models

Coordinates and angles can be defined in other programs and imported into Dynamo as models. When an external file is imported as a model, Dynamo will fill the points fields of the models (and possibly other geometric parameters depending on the model type), covering the Point input stage of the model. The geometry computation stage can then be performed inside Dynamo.

dmimport

Command line options

Models can read an write normally using dread and dwrite. Basic models use the extension ".omd" (object model).

Adding a model to a catalogued tomogram

A file representing a model created on a catalogued tomogram will lay in a predefined position. For instance, a model named someModel created by Dynamo in one of its catalogue-based tomogram viewers for the volume indexed as 2 in a catalogue named my Catalogue will be automatically stored in the position: myCatalogue /volume_2/models/someModel.omd

Now, if you have produced a model object myModel independently of the catalogue system, and want to embed it and assign it to a catalogued tomogram, you might have the temptation of just saving it as dwrite(myModel,'myCatalogue /volume_2/models/myModel.omd'). This is not correct, as the catalogue needs to preserve some internal links

1. Assign the model with a Dynamo command

   dcm -c myCatalogue -l 2 -am myModel.omd

2. Alternatively, you can tell the catalogue to relink all the files found in the models folder of one or more volumes.

   dcm -c myCatalogue --relinkAllModelFiles

If you have created a model

Plotting models

An easy way to visualize the contents of a model object is with the ezplot method. Type symply: >> myModel.ezplot to get a menu of plotting options.