Difference between revisions of "Daverage"
(Created page with " <tt>daverage</tt> is the basic command line option for averaging particles in a data folder using alignment parameters expresed inside a table. == Syntax == The ba...") |
(→Syntax) |
||
(7 intermediate revisions by the same user not shown) | |||
Line 11: | Line 11: | ||
where <tt>output</tt> is an structure recording several items (including of course the density map). If you want to use a linux-like notation, you can produce a left-hand-side output wuth the flag <tt>ws</tt> (short for ''workspace''), i.e. | where <tt>output</tt> is an structure recording several items (including of course the density map). If you want to use a linux-like notation, you can produce a left-hand-side output wuth the flag <tt>ws</tt> (short for ''workspace''), i.e. | ||
− | + | <tt> daverage myData -t myTable.tbl -ws output</tt> | |
− | <tt> daverage myData -t myTable.tbl -ws output</tt> | ||
== Input== | == Input== | ||
Line 27: | Line 26: | ||
=== Options === | === Options === | ||
+ | |||
== Output == | == Output == | ||
The output structure has several fields. | The output structure has several fields. | ||
+ | * <tt> .average_raw:</tt> <br /> without compensation for overweighting of fourier pixels | ||
+ | * <tt> .average: </tt> <br /> with compensation for the fourier overweighting | ||
+ | * <tt> .fweight:</tt> <br /> map of overrrepresentation of fourier components in the output property <tt>.average_raw</tt> | ||
+ | * <tt> .fmask: </tt> <br /> binary mask denoting available fourier coefficients | ||
+ | * <tt> .variance: </tt> <br /> variance map | ||
+ | * <tt> .fsc: </tt> <br /> fsc values | ||
+ | * <tt> .fsc_labels: </tt> <br /> useful information to annotate fsc plots | ||
+ | * <tt>.tags:</tt> <br /> list of tags that did actually contribute to the averaging procedure. This is useful to control which is the final result of confronting which data is available, which tags are marked in the table, and also which particles where excluded. | ||
+ | * <tt> .nanContributions</tt> <br /> map with the number of particles that contributed a NaN value for each pixel. | ||
Line 36: | Line 45: | ||
=== Rotation and shift=== | === Rotation and shift=== | ||
+ | |||
+ | Particles and shifted, then rotated, following the alignment parameters in the table. By convention, positions 4:6 and 7:9 in a the <tt>i</tt>-th row in a table denote respectively the shifts and rotation parameters that are performed on the template to match the particle in that <tt>i</tt>-th position (first rotation, then shifting). The shifts and angles that bring the particle to match the template are the ones that parametrize the inverse transform: | ||
+ | |||
+ | <nowiki>shiftsParticle =-myTable(i,4:6); | ||
+ | eulersParticle =-fliplr(myTable(i,:7:9));</nowiki> | ||
+ | |||
+ | and the operation that creates the aligned particle can be written as : | ||
+ | |||
+ | <tt>rotatedParticle = dynamo_shift_rot(particle, shiftsParticle, eulersParticle);</tt> | ||
+ | |||
+ | Note that the volume <tt>rotatedParticle</tt> will contain some NaN (not-a-number) values, as explained below. | ||
+ | |||
+ | ==== Corner effects ==== | ||
+ | |||
+ | Rotation causes [[Border alignment artifact|undefined values in the corners of a rotated volume]]. By default, when a cube is rotated, the resulting sharp edge is created in the rotated version of the cube. Alternatively, one can switch on the flag <tt>implicitRotationMasking</tt> (to value 1). This will compute the values of the rotated volume only inside an interior sphere, making "almost" invisible the effect of the edges. Only "almost": shifting acts exacly like rotation, introducing edges inside the rotated volume. As we assume that shifts shouldn't be too large, the effects of the shifts are less evident. | ||
+ | |||
+ | ''Dynamo'' keeps track of the pixels that are brought from out-of-scope areas: | ||
+ | # The contribution of such a pixel to the average is zero. | ||
+ | # These pixels are accumulated into a counter. | ||
=== Normalization=== | === Normalization=== | ||
+ | |||
+ | Particles will be normalized only in the flag for normalization is active. | ||
+ | The function internally used to run this normalization is <tt>dynamo_normalize_roi</tt>. | ||
+ | |||
+ | By default, when <tt>daverage</tt> is invoked inside a project, a normalization will be performed, using the average and standard deviation on the intensities of the aligned particle inside the [[alignment mask]] | ||
=== NaN compensation === | === NaN compensation === | ||
+ | Rotation and shiftings bring into the rotated volume a set of undefined values. They are equated to zero during the summation of the aligned particles. | ||
+ | |||
+ | Thus, if you have N particles, in these sum map some pixels will represent the summation of ''real'' contributions of N particles, and some will represent the contribution of less particles. In order to compensate this, the default behaviour of ''Dynamo'' is as follows: the average intensity is computed by dividing in each pixels the sum intensity (including the zero contributions) by the number of actual contributions. | ||
+ | |||
+ | The number of out-scope-contributions is returned in the left hand side of the command as property <tt>'nanContributions'</tt>. | ||
+ | |||
+ | This default behaviour can create visually annoying effects outside of the interior mask, specially if your particles have preferential orientations. If you want to avoid them, you can switch off the option <tt>explicitBalanceNan</tt>, which will cause ''Dynamo'' to create the average by simply summing all the intensities and dividing them by the total number of particles for ''every'' pixel, thus ignoring different numbers of contributions from pixel to pixel. | ||
=== Missing wedge compensation=== | === Missing wedge compensation=== | ||
+ | |||
+ | [[Fourier compensation during averaging | Missing wedge compensation]] will be activated whenever the flag <tt>fc</tt> or <tt>fourier_compansate</tt> is used. |
Latest revision as of 15:09, 13 October 2017
daverage is the basic command line option for averaging particles in a data folder using alignment parameters expresed inside a table.
Contents
Syntax
The basic syntax of the command is:
output = daverage('myData','t','myTable.tbl');
where output is an structure recording several items (including of course the density map). If you want to use a linux-like notation, you can produce a left-hand-side output wuth the flag ws (short for workspace), i.e.
daverage myData -t myTable.tbl -ws output
Input
Data folder
The location of the particles can be passed through:
Table
A regular Dynamo table, than can be passed as file or numeric matrix.
Options
Output
The output structure has several fields.
- .average_raw:
without compensation for overweighting of fourier pixels - .average:
with compensation for the fourier overweighting - .fweight:
map of overrrepresentation of fourier components in the output property .average_raw - .fmask:
binary mask denoting available fourier coefficients - .variance:
variance map - .fsc:
fsc values - .fsc_labels:
useful information to annotate fsc plots - .tags:
list of tags that did actually contribute to the averaging procedure. This is useful to control which is the final result of confronting which data is available, which tags are marked in the table, and also which particles where excluded. - .nanContributions
map with the number of particles that contributed a NaN value for each pixel.
Averaging procedure
Rotation and shift
Particles and shifted, then rotated, following the alignment parameters in the table. By convention, positions 4:6 and 7:9 in a the i-th row in a table denote respectively the shifts and rotation parameters that are performed on the template to match the particle in that i-th position (first rotation, then shifting). The shifts and angles that bring the particle to match the template are the ones that parametrize the inverse transform:
shiftsParticle =-myTable(i,4:6); eulersParticle =-fliplr(myTable(i,:7:9));
and the operation that creates the aligned particle can be written as :
rotatedParticle = dynamo_shift_rot(particle, shiftsParticle, eulersParticle);
Note that the volume rotatedParticle will contain some NaN (not-a-number) values, as explained below.
Corner effects
Rotation causes undefined values in the corners of a rotated volume. By default, when a cube is rotated, the resulting sharp edge is created in the rotated version of the cube. Alternatively, one can switch on the flag implicitRotationMasking (to value 1). This will compute the values of the rotated volume only inside an interior sphere, making "almost" invisible the effect of the edges. Only "almost": shifting acts exacly like rotation, introducing edges inside the rotated volume. As we assume that shifts shouldn't be too large, the effects of the shifts are less evident.
Dynamo keeps track of the pixels that are brought from out-of-scope areas:
- The contribution of such a pixel to the average is zero.
- These pixels are accumulated into a counter.
Normalization
Particles will be normalized only in the flag for normalization is active. The function internally used to run this normalization is dynamo_normalize_roi.
By default, when daverage is invoked inside a project, a normalization will be performed, using the average and standard deviation on the intensities of the aligned particle inside the alignment mask
NaN compensation
Rotation and shiftings bring into the rotated volume a set of undefined values. They are equated to zero during the summation of the aligned particles.
Thus, if you have N particles, in these sum map some pixels will represent the summation of real contributions of N particles, and some will represent the contribution of less particles. In order to compensate this, the default behaviour of Dynamo is as follows: the average intensity is computed by dividing in each pixels the sum intensity (including the zero contributions) by the number of actual contributions.
The number of out-scope-contributions is returned in the left hand side of the command as property 'nanContributions'.
This default behaviour can create visually annoying effects outside of the interior mask, specially if your particles have preferential orientations. If you want to avoid them, you can switch off the option explicitBalanceNan, which will cause Dynamo to create the average by simply summing all the intensities and dividing them by the total number of particles for every pixel, thus ignoring different numbers of contributions from pixel to pixel.
Missing wedge compensation
Missing wedge compensation will be activated whenever the flag fc or fourier_compansate is used.