# Daverage

`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.