Scale Methods

This page explains the three ways exo2micro can estimate the pre-stain scale factor, when to use each, and what the output files look like for each.

The problem

After alignment, exo2micro needs to subtract a scaled version of the pre-stain image from the post-stain image:

difference = post − scale × pre

Choosing the right scale matters. Too low and you undersubtract (the background bleeds through and masks microbe signal). Too high and you oversubtract (the background “becomes negative” and real microbe features appear suppressed). The exact right value depends on how the autofluorescent background scaled between pre-stain and post-stain imaging.

Auto (Moffat fit) — the default

What it does

exo2micro computes the log-ratio log₁₀(post/pre) at every pixel where both images have signal, bins this into a histogram, and fits a Moffat profile — that’s:

amp × (1 + ((x − μ) / α)²)^(−β)

— to the left wing of the distribution mirrored across the peak. The fitted peak centre μ is the background scale estimate, and scale = 10^μ.

Why a Moffat fit? The log-ratio distribution has a sharp central peak from autofluorescent background pixels (which have a consistent ratio) and a long right tail from microbe pixels (which have a higher ratio because they gained fluorescence). We want the peak centre, not the tail. A Gaussian fits the peak poorly because microscopy noise has longer tails than a normal distribution; a Moffat profile matches the empirical peak shape much better.

When to use it

This is the right choice almost always. Use it as your default.

Output

  • processed/{sample}/{dye}/tiff/04_difference_difference.tiff — the scaled difference image

  • ...fits/04_difference_difference.fits — same, with the scale factor in the SCALE header keyword and SCALEK = 'moffat'

  • ...pipeline_output/difference_image.png — visualization

  • ...pipeline_output/ratio_histogram.png — the fit itself, which you should check

Ratio percentile

What it does

Computes the per-pixel ratio post/pre at every pixel where both images have signal, takes the chosen percentile of that distribution, and uses it as the scale factor.

You enable this by setting the scale_percentile parameter to a float value between 0 and 100 (decimals like 99.1 are accepted). This is also exposed in the GUI via the Scale dropdown.

Importantly, setting scale_percentile does not replace the Moffat fit — the Moffat-fit difference image is still produced. Instead, an additional difference image is produced using the percentile-derived scale. This lets you compare the two side by side in the excess_heatmap.png plot (which overlays both scale lines) and in the two difference TIFFs.

When to use it

The percentile method is most useful when:

  • You have a clear intuition about what fraction of your tissue should be “background only” vs. “microbe signal”. If you expect roughly half the tissue to have microbes, the 50th percentile of the ratio distribution is a reasonable estimate of the background-only scale.

  • You want a quick sanity check against the Moffat fit by picking a percentile you think should land in the background cluster (typically between 20 and 70 for most samples).

  • You’re building a processing procedure for a new sample type where you don’t yet trust the Moffat fit and want a percentile-based control you understand exactly.

Watch the percentile value you pick. If you ask for the 99th percentile of a ratio distribution where even 1% of pixels are microbes, you’ll land in the microbe tail and get an implausibly large scale. Moderate percentiles (30-70) are usually the right range for this method.

Output

With scale_percentile=50 set, in addition to the standard Moffat outputs, you get:

  • 04_difference_difference_percentile_p50{suffix}.tiff

  • 04_difference_difference_percentile_p50{suffix}.fits (with SCALE header recording the computed value and SCALEK = 'percentile_p50')

  • difference_image_percentile_p50{suffix}.png

Where {suffix} reflects all non-default parameters in the run, including the percentile value itself.

Manual override

What it does

You type in an exact scale value and exo2micro uses it verbatim. Set with the manual_scale parameter (a float). Also exposed in the GUI via the Scale dropdown.

Like scale_percentile, setting manual_scale doesn’t replace the Moffat fit — it adds a third difference image that uses your value.

When to use it

  • You’re reproducing a published result that specified a particular scale factor.

  • You’ve already processed the dataset once with auto scale, saw the Moffat fit land somewhere slightly off, and want to try a nearby value by hand.

  • You’re doing sensitivity analysis — running the same sample with several nearby scale values to see how stable the subtraction is.

  • The Moffat fit failed (e.g. your sample has an unusually distributed ratio distribution) and you need to bypass it.

Output

With manual_scale=1.42 set, in addition to the standard Moffat outputs, you get:

  • 04_difference_difference_manual{suffix}.tiff

  • 04_difference_difference_manual{suffix}.fits (with SCALE = 1.42 and SCALEK = 'manual')

  • difference_image_manual{suffix}.png

All three at once

You can set scale_percentile and manual_scale simultaneously. Stage 4 will compute all three: Moffat, percentile, and manual. The excess_heatmap.png plot overlays all three scale lines in different colours, making it easy to see which one best tracks the peak of the pre vs. post density ridge.

This is the recommended workflow when you’re deciding what scale to use for a new dataset: run all three, compare the difference image PNGs, pick the one that looks best, and note that value for future runs.

Reading the excess heatmap

The excess_heatmap.png plot in pipeline_output/ is the key visual for comparing scale choices. It shows a 2-D histogram of pre vs. post brightness with the diagonal reflection subtracted off — anything visible is excess post-stain signal. Scale lines are overlaid in different colours:

  • Green (#00cc88) — Moffat fit

  • Orange (#ff9933) — ratio percentile

  • Pink (#ff3366) — manual value

A well-chosen scale passes along the ridge of the background distribution, leaving the bright excess cells (the microbe signal) cleanly above the line.

Todo

Add an example excess_heatmap.png here showing all three scale lines overplotted. Save to docs/source/users/_images/excess_heatmap_example.png.