Module areacor

source code

Correct from counts per pixel to counts per unit area on the detector.

Usage
=====

Example::

    # construct the correction based on a detector measurement
    from reflectometry.reduction import load, measured_area_correction
    floodfill = load('detector measurement')
    areacor = measured_area_correction(floodfill)

    # apply the correction
    data = load(d).apply(areacor)

If you want to the pixels to have equal area then you need to include
a rebin=True flag::

    areacor = measured_area_correction(floodfill,rebin=True)

You can also set the areacor.rebin attribute directly.

If you know the pixel widths in x and y then you don't have to extract
them from a measurement, but can instead use::

    areacor = area_correction(wx,wy,source="provenance")

Certain instruments have predefined area corrections, which are
returned by the area_correction() method of the refldata object.

Limitations
===========

The correction applies independently in x and y using the sum of the pixels
across that detector dimension.  Small detector rotations and misaligned
wires will lead to artificial broadening.

The correction does not apply if there are other detector artifacts, such as
pixel efficiency variation.  Sliding the detector across a narrow slit and
summing the total counts across the detector will show any efficiency
variation.  We do not attempt to correct for this.

This theory also assumes the floodfill is uniform, which will depend on
how the measurement is performed.  For example, incoherent scattering
off water will yield higher intensities closer to the beam, and measurements
of a point source with a flat detector will yield higher counts where the
detector is nearer the point.  Data not taken in the ideal condition of
sliding the detector behind a narrow slit while maintaining uniform intensity
from the beam will need to scaled appropriately before estimating pixel widths.

Even after correcting for pixel widths in x and y, there may be a residual
signal on the detector.  This can be viewed by applying the detector
correction to the floodfill itself.  As a second order pixel area effect due
to variations in wire position across the rows and columns of the detector,
the pixels could be further scaled by this variation.  The scale factor
should be S = nx*ny * F/sum(F), where F is the corrected detector image.
This is not implemented here.

Theory
======

Assuming the pixels have none uniform area, we can estimate the area
of each pixel by looking at the counts across the detector in a floodfill
environment.

First lets define the detector.  We will do so in one dimension, but
it is a separable problem which can be applied independently in the
x and y directions.

Detector has varying width pixels:

    |......|....|.....|....|
     w_1   w_2        w_n

    L = sum(w) = length of the detector
    C_i = measured counts in cell i
    D = sum(C)/L = average flux on the detector

Given a uniform flux on the detector, what is the probability of seeing
the particular measured set of counts P(C|w).  We will assume a Poisson
distribution for the counts in the individual pixels.

    D = flux in counts/unit area
    lambda_i = D w_i = expected counts in cell i
    P_i(C_i|D w_i) = exp(-D w_i) (D w_i)**C_i / C_i!
    P(C|w) = prod P_i(C_i|D w_i)

Minimize the log probability by setting the derivative to zero:

    log P = sum log P_i
    log P_i = -D w_i + C_i log D w_i - log C_i!

    d/dw_i log P = d/dw_i log P_i
                 = d/dw_i (-D w_i) + C_i d/dw_i log D w_i
                 = -D + C_i D / (D w_i)
    d/dw_i log P = 0
        => D = C_i/w_i
        => w_i = C_i/D = L * C_i / C