| Bsoft 1.9 Bernard's software package

- Main Page
- Namespaces
- Classes
- Files

- File List
- File Members

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros
Functions | Variables
img_resolution.cpp File Reference

Library routines to estimate resolution. More...

`#include "Bimage.h"`
`#include "img_resolution.h"`
`#include "rwFSC_XML.h"`
`#include "ps_plot.h"`
`#include "trigonometry.h"`
`#include "utilities.h"`

Go to the source code of this file.

## Functions
Bplot * | img_resolution (Bimage *p, Bimage *pmod, Bimage *prealmask, Bimage *pftmask, double hi_res, double aligned_res, double sampling_ratio)
| Calculates resolution measures. More...
double * | img_resolution_display (Bplot *plot, float *cutoff)
| Calculates the resolution estimates from a plot generated by img_resolution. More...
double * | img_resolution_display (Bplot *plot)
| Calculates the resolution estimates from a plot generated by img_resolution. More...
int | img_resolution_from_two_images (Bstring &image_file, Bstring &ref_file, Bstring &real_mask_file, Bstring &ft_mask_file, double resolution, double aligned_res, Vector3< float > sampling, double sampling_ratio, float *cutoff, Bstring &ps_file, Bstring &xml_file, Bstring &tsv_file, Bstring &proj_file)
| Calculates the resolution from two images. More...

## Variables
int | verbose

## Detailed Description

Library routines to estimate resolution.

Author
  Bernard Heymann

Date
  Created: 20000611
  Modified: 20150203

Definition in file img_resolution.cpp.

## Function Documentation

Bplot* img_resolution | ( | Bimage * | p,
|  | Bimage * | pmod,
|  | Bimage * | prealmask,
|  | Bimage * | pftmask,
|  | double | hi_res,
|  | double | aligned_res,
|  | double | sampling_ratio
| ) |  |

Calculates resolution measures.

Parameters

  *p | first image (typically a raw or experimental image).
  *pmod | second image (typically a model image).
  *prealmask | real space mask (can be fuzzy).
  *pftmask | reciprocal space mask (0 & 1, indicating inclusion of structure factors).
  hi_res | high resolution limit for calculation.
  aligned_res | high resolution limit for validation.
  sampling_ratio | radial sampling ratio (1 for per voxel sampling).

Returns
  Bplot* plot with 5 columns for each image.

      The two images must be of the same dimensions.
      The two images are packed into a combined complex data set (the first
      image in the real part and the second image in the imaginary part).
      This is Fourier transformed and the individual transforms calculated
      based on the Hermitian or Friedel symmetry of transforms of real space
      data sets. The calculations are done on only half of the data set
      because the two halves are Friedel symmetry related.

      An optional input mask can be used to exclude parts of the transforms.
      The mask must consist of 0's and 1's, where 1 indicates inclusion.

      FRC: Fourier ring/shell correlation
      -----------------------------------
      Saxton & Baumeister (1982) J. Microscopy 127, 127-138
      de la Fraga et al. (1995) Ultramicroscopy 60, 385-391
      This is also called Fourier shell correlation (FSC) in 3D.
                 sum(|F1|*|F2|*cos(phi1 - phi2))
      FRC/FSC = ---------------------------------
                sqrt( sum(|F1|^2) * sum(|F2|^2) )

      DPR: Differential phase residual
      --------------------------------
      Frank & Boublik (1981) Science 214, 1353-1355
      The resolution is determined by a sum of the phase differences weighed by the
      sum of the amplitudes:
                 sum( (|F1| + |F2|) * (phi1 - phi2)^2 )
      DPR = sqrt(--------------------------------------)
                            sum(|F1| + |F2|)

      SSNR: Spectral signal-to-noise ratio
      ------------------------------------
      Unser et al. (1987) Ultramicroscopy 23, 39-52
      The idea is that the signal-to-noise ratio is given by the model amplitudes
      divided by the noise.  The noise in the first data set is calculated by
      subtracting the second data set (the model).  The SNR is then estimated by
      subtracting one to compensate for residual noise in the model:
               sum(|F2|^2)
      SSNR = --------------  -  1
             sum(|F1-F2|^2)

      RAB: R(A+B) figure of merit
      ---------------------------
      Winkelmann et al. (1991) J. Cell Biology 114, 701-713
      The measure given in the paper has been adapted to divide by the sum of the
      amplitudes rather than just the amplitudes of the first data set, thus it
      becomes the difference divided by the sum:
             sum(|F1 - F2|)
      RAB = ----------------
            sum(|F1| + |F2|)

      Individual structure factor figure of merit
      -------------------------------------------
      Each individual structure factor/reflection/voxel is assigned a FOM based
      on the phase and amplitude differences, and a measure of the S/N ratio:
                                |A1 - A2|              A1 + A2
      FOM = cos(delta_phi)*(1 - --------- )*(1 - exp(- ------- ) )
                                 A1 + A2                StDev
      where delta_phi is the phase difference, A1 and A2 are the amplitudes, and
      StDev is the standard deviation of the combined transform (a measure of the
      noise in the two data sets).

Definition at line 94 of file img_resolution.cpp.

double* img_resolution_display | ( | Bplot * | plot,
|  | float * | cutoff
| ) |  |

Calculates the resolution estimates from a plot generated by img_resolution.

Parameters

  *plot | resolution plot information.
  *cutoff | cutoff values for the 4 resolution estimators.

Returns
  double* array of 4 resolution estimates.

      The plot must have 5 columns for each page as follows:
      1.  spatial frequency
      2.  FSC
      3.  DPR (in degrees)
      4.  SSNR
      5.  R+AB

Definition at line 393 of file img_resolution.cpp.

double* img_resolution_display | ( | Bplot * | plot | ) |

Calculates the resolution estimates from a plot generated by img_resolution.

Parameters

  *plot | resolution plot information.

Returns
  double* array of 4 resolution estimates.

      The plot must have 2 columns for each page as follows:
      1.  spatial frequency
      2.  FSC

      The resolution estimates are calculated from the FSC curve at 4 cutoffs:
      1.  0.143   gold standard (independent data sets)
      2.  0.3     cutoff for halfsets (not necessarily independent halfsets)
      3.  0.5     conservative cutoff
      4.  0.9     cutoff for selecting a resolution limit for the next round of processing.

Definition at line 476 of file img_resolution.cpp.

int img_resolution_from_two_images | ( | Bstring & | image_file,
|  | Bstring & | ref_file,
|  | Bstring & | real_mask_file,
|  | Bstring & | ft_mask_file,
|  | double | resolution,
|  | double | aligned_res,
|  | Vector3< float > | sampling,
|  | double | sampling_ratio,
|  | float * | cutoff,
|  | Bstring & | ps_file,
|  | Bstring & | xml_file,
|  | Bstring & | tsv_file,
|  | Bstring & | proj_file
| ) |  |

Calculates the resolution from two images.

Parameters

  &image_file | image file name.
  &ref_file | reference image file name.
  &real_mask_file | real space mask file name.
  &ft_mask_file | reciprocal space mask file name.
  resolution | high resolution limit for calculation.
  aligned_res | high resolution limit for validation.
  sampling | pixel/voxel size.
  sampling_ratio | spatial frequency sampling ratio.
  *cutoff | 4-value list of cutoff values.
  &ps_file | Postscript output file name.
  &xml_file | XML output file name.
  &tsv_file | tab-separated values output file name.
  &proj_file | output projection file name.

Returns
  int 0.

      The average FOM and number of FOM values in each resolution shell is determined.

Definition at line 552 of file img_resolution.cpp.

## Variable Documentation

int verbose