accumulate¶

speclite.accumulate.accumulate(data1_in, data2_in, data_out=None, join=None, add=None, weight=None)[source] [edit on github]¶

Combine the data from two spectra.

Values x1 and x2 with corresponding weights w1 and w2 are combined as:

x12 = (w1*x1 + w2*x2)/(w1 + w2)

If no weight field is present for either input, a weight of one is used. If either input array is masked, weights for masked entries will be set to zero. The output contains values for x12 and the accumulated weight:

w12 = w1 + w2

For example:

>>> data1 = np.ones((10,), dtype=[('flux', float), ('ivar', float)])
>>> data2 = np.ones((10,), dtype=[('flux', float), ('ivar', float)])
>>> result = accumulate(data1, data2, add='flux', weight='ivar')
>>> np.all(result[:3] ==
... np.array([(1.0, 2.0), (1.0, 2.0), (1.0, 2.0)],
... dtype=[('flux', '<f8'), ('ivar', '<f8')]))
True

Any fields common to both inputs can also be copied to the output:

>>> data1 = np.ones((10,), dtype=[('wlen', float), ('flux', float)])
>>> data2 = np.ones((10,), dtype=[('wlen', float), ('flux', float)])
>>> result = accumulate(data1, data2, join='wlen', add='flux')
>>> np.all(result[:3] ==
... np.array([(1.0, 1.0), (1.0, 1.0), (1.0, 1.0)],
... dtype=[('wlen', '<f8'), ('flux', '<f8')]))
True

The actual calculation of x12 uses the expression:

x12 = x1 + (x2 - x1)*w2/(w1 + w2)

which has better numerical properties when many spectra are iteratively accumulated using the following pattern:

>>> result = None
>>> data = np.ones((10,100),
... dtype=[('wlen', float), ('flux', float), ('ivar', float)])
>>> for row in data:
...     result = accumulate(data1_in=result, data2_in=row, data_out=result,
...                         join='wlen', add='flux', weight='ivar')
>>> np.all(result[:3] ==
... np.array([(1.0, 1.0, 10.0), (1.0, 1.0, 10.0), (1.0, 1.0, 10.0)],
... dtype=[('wlen', '<f8'), ('flux', '<f8'), ('ivar', '<f8')]))
True

With this pattern, the result array is allocated on the first iteration and then re-used for all subsequent iterations.

Parameters:

data1_innumpy.ndarray or numpy.ma.MaskedArray or None: First structured numpy array of input spectral data.
data2_innumpy.ndarray or numpy.ma.MaskedArray: Second structured numpy array of input spectral data.
data_outnumpy.ndarray or None: Structured numpy array where output spectrum data should be written. If None is specified, then an appropriately sized array will be allocated and returned. Use this method to take control of the memory allocation and, for example, re-use the same output array for iterative accumulation.
join: string or iterable of strings or None.: A field name or a list of field names that are present in both inputs with identical values, and should be included in the output.
addstring or iterable or None.: A field name or a list of field names that are present in both inputs and whose values, x1 and x2, should be accumulated as x12 in the output.
weightstring or None.: The name of a field whose values provide the weights w1 and w2 used to calculate the accumulated x12 = w1*x1 + w2*x2. If the named field is not present in either input a weight value of one will be used. The output array will contain a field with this name, if it is not None, containing values for w12.

Returns:

numpy.ndarray: Structured numpy array of accumulated result, containing all fields listed in the join, add, and weight arguments. Any values associated with a zero weight sample should be considered invalid.

Navigation

accumulate¶