Skip to content

Design.md

Latest commit

 

History

History
95 lines (62 loc) · 5.66 KB

Design.md

File metadata and controls

95 lines (62 loc) · 5.66 KB
Raw

Organization of the code

The goal of this document is to specify the design of the software used for alignment, excluding the structure detection software.

The description here is for production code, therefor only for executable python (.py) files and shell (.sh) files.

The parameters for each of these files should be documented using the argparse library.

These files should reside in the src subdirectory and a .md file should be added to describe the role of each script.

Library files ('.py' files that are imported, not executed)

These files should reside in the directory src/lib

Integration into pipeline

script files should conform to the api expected by the database, and be tested against the database.

Notebook files (.ipynb)

Notebooks are sandboxes for trying and debugging new code. Once the code is stable, it should be exported as a .py file into the src directory. In the dictionary each developer keeps their own notebooks. (one can always bring back .py files into a notebook by using the %load magic.

While these files are kept in the repository, there is no requirement to keep them uniform or documented.

Attribution

At any time there must be only one version of each file in src (github automatically keeps all versions). Thus there should be no John' version and Bill's version, only a single version. The pydoc in the file should attribute the file to a pragrammer or a sequence of programmers.

Lucidchart diagrams

Alignments

Coordinate systems:

  • atlas coordinates: coordinates units are in microns, origin is at the center of the brain. This is a rescaled version of the Yncong (10,10,20) coordinate system.
    • We will investiage syncronizing our atlas to other standard atlases.
  • Stack coordinates: Coordinate units are in microns, origin is at (0,0,0) of the containing box (top,left, first slice).
  • Neuroglancer coordinates: a scaled version of the stack coordinate system, where the units are (pixel x, pixel y, section number)

Transformations:

atlas <-> stack,

generated by alignments implemented here. There will be many transformations so I recommend creating a class with subclasses for different types of transformation. An instance will include both the code for the transformations in both directions and the set of parameters.

  • atlas2stack: takes as input atlas coordinates, outputs stack coordinates
  • stack2atlas takes as input stack coordinates, outputs atlas coordinates

stack <-> neuroglancer

maintained as part of the pipeline because it depends on the resolution of the images, distance between sections etc.

  • neuroglancer2stack
  • stack2neuroglancer

stack <-> stack

This is a transformation between two stacks, two stacck coordinates, generated using rough alignments (see below) This is combined with the stack to atlas alignment of one of the image stacks (reference image currently DK52)

Landmark based alignments

Landmark based alignment takes as input paired points (COMs):

  • Identified COMs: generated by anatomist, rough alignment, or structure detection (Kui). These COMs are expressed using stack coordinates.
  • Atlas COMs: These are COMs that are part of the atlas, they are expressed in atlas coordinates.

Landmark based alignments find a transformation from stack coordinates to atlas coordinates that (approximately) maps the identified COMs to the atlas COMs. The transformation is constrained to be in a restricted class. Some such classes are:

  • rigid transformation: can be solved algebraicly.
  • affine transformation Implemented.
  • spline-based transformation - we plan to implement next.
  • Demon based diffeomorphic transformation.

Evaluating the quality of landmark-based alignments.

We want to quantify the bias and variance of the identified landmarks. To do so we take several brains (n), find the transformation from identified coms to landmark coms for each brain. This gives use a set of n xyz coordinates for each identified landmark, all in atlas coordinates. We subtract from each identified COM xyz the xyz of the corresponding atlas COM. The result is n numbers for each coordinate of each stracture. We visualize the distribution of these numbers using a box-plot.

Using the box plot we can evaluate several things:

  1. How good are the identified coms: we say that <50ms is very good, < 100ms is good <500ms is fair, otherwise poor.
  2. Bias : how far is the mean of the points from zero.
  3. Variance: How far are the points from each other

Large variance indicates poor performance. Small variance with large bias indicates a systemic error, which can come from either mismatch with the atlas COMs or from the transformation being too restricted to capture the variability in shape.

Rough Alignments

Rough alignments take as input two stacks, one of which is a reference stack, which has a trusted alignment with the atlas. It finds a transformation between the two stacks, and combines it with the alignment of the reference to the atlas to create an alignment of the brain to the atlas:

(moving stack -> reference stack) + (reference stack -> atlas) = (moving stack -> atlas)

Right now we are using a neurotrace blue stain as a reference (DK52). It might be necessary to create a different reference when we move to a different staining method.

transformations generated by rough alignments:

  • rigid
  • affine
  • spline-based
  • Diffeomorphism