A model has three basic functionalities, applied sequentially:
- 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.
- Geometrical computation stage.
- Converts the input into particle positions.
- Archiving the annotations.
- Models are naturally integrated inside the catalogue system, making the process of extracting particles very easy.
For the first two functionalities, Dynamo offers different types of models, adapted to the different geometries that you might encounter: filaments, vesicles, irregularly shaped membranes, isolated particles, pseudo-crystaline arrangements....
- 1 Working with models
- 2 Basic operations with models
- 3 Types of models
- 4 Archiving models
- 5 Importing models
- 6 Command line options
Working with models
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.
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.
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
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
- Main article: Filament models
Adequate for particles evenly distributed along filaments. Subtomograms 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.
- Main article: Membrane models
When particles are regularly distributed on a membrane (or a membrane fraction) that cannot be approximated by a vesicle.
- Main article: Vesicle models
Adequate for particles evenly distributed on spheres or ellipsoids.
- Main article: Dipole set models
Used to mark in a single model different groups of points. Typically used to annotate the orientations of isolated particles, or to annotate groups vesicles of different radius in a single tomogram.
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.
When a model related to a catalogue is in the Matlab workspace as a variable, you can return it to the catalogue with the method saveIntoCatalogue. This is useful to extract archived models, operate on them, and put them back into the catalogue.
- You want to change the distance between consecutive crop points in a model which is stored with the name myFilename . The model is catalogued, and you want to put it back into the catalogue after updating it;
- m = dread('myFilename'); # reads the model object into the matlab workspace with the arbitrary variable name m
- m.subunits_dz = 10; # changes the parameter value
- m.updateCrop(); # recompute the crop_points and crop_angles
- Main article: 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.
The most important function for manual importing of models is 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
- Main article: Adding models to catalogued volumes
Models can be created, imported or edited in the workspace, using the command line tools of Matlab and/or Dynamo. A model object that has been extracted from the catalogue can be returned to it after edition using the method save, i.e.
m = dread(<someModelFileInACatalogue>); ... your edition operations ... m.saveIntoCatalogue();
When a model is generated from scratch in the workspace, you need to add it to a volume explicitly.
Extracting models from catalogued tomograms
- Main article: Extracting models from catalogued tomograms
Models in a catalogue are just regular files defined in well defined locations. A model named 'myModel' in the catalogue 'myCatalogue' will be stored in the file myCatalogue/volume1/models/myModel.omd
They can be accessed with the dcm command:
- dcm -c myCatalogue -l m -ws o
- will list all the models in all volumes in the catalogue (as a cell array of files in the result property output variable o).
- dcm -c myCatalogue -l m -i 4 -ws o
- will list the all the models in the tomogram indexed as number 4 the catalogue (as a cell array of files in the output variable o).
There is a simplified syntax through the dynamo_catalogue_models command:
- files = dcmodels(myCatalogue);
- sets in file array files all model files found inside the catalogue.
- files = dcmodels(myCatalogue,'i',2);
- sets in file array files all model files found inside volume number 1.
- files = dcmodels(myCatalogue,'nameContains','vesicle');
- adds the condition that the file names contain the string 'vesicle'
All models have a set of methods that start with the string plot
Additionally each model class offers its own set of plotting options. For instance, the model Vesicle can generate surface plots, and includes thus the methods plotSurface and plotMesh
An easy way to visualize the contents of a model object from the command line is with the ezplot method. Type simply: |>> myModel.ezplot}}| to get a menu of plotting options.
Extracting particles from a model
Normally, you want to generate a data folder containing cropped particles form several models simultaneously. But sometimes, you are interested in extracting the particles from just one model into a single data folder in order to start working on your data. This can be done while you are navigating the corresponding tomogram with dtmslice, through the menu [Active model] -> [Crop particles from active model], which will open thedtcrop command in its GUI form.
From the command line, you can just extract the volume and the table contained in the model and use the command line form of the dtcrop command.
m = dread(myModelFile); t = m.grepTable(); # here you can check the contents of table t tomogram = m.cvolume.fullFileName();% this recovers the name of the original tomogram. dtcrop(tomogram,t,'targetFolder',64);