Utilities

This sub-package contains helpful utilities for Lightkurve.

BitSet

A set-like class for bitwise data with support for integer representation

class lkdata.utils.bitset.BitSet(iterable=None)

Bases: MutableSet, Hashable

A data type for bitwise objects.

This datatype combines the utility of sets and the succinct representation of integer numbers as used for data quality flags in astronomical data. Integers are treated as sets of their constituent powers of 2.

add(value)

Add an element.

bin()

Return binary represenation

static breakdown(item)

Breaks down a given item into a single set of bitwise components

Return type:

set

Parameters:

itemUnion[int, str, Iterable]

An integer, binary integer, or collection of integers to be broken down

discard(value)

Breakdown value to powers of 2, remove common elements

remove(value)

Breakdown value to powers of 2 and remove

Raises:

KeyError - If not all powers of 2 exist within BitSet

type

alias of int

Uncertainty

The uncertainty developed for lkdata is based on the astropy.nddata.NDUncertainty module, as of the v7.0.0 release.

Uncertainty class and methods for use with numerical lkdata objects This code is modified from astropy.nddata.nduncertainty v7.0.0 release distributed under the following MIT license:

Licensed under a 3-clause BSD style license - see LICENSE.rst Copyright (c) 2011-2024, Astropy Developers All rights reserved.

exception lkdata.utils.uncertainty.IncompatibleUncertaintiesException

Bases: Exception

This exception should be used to indicate cases in which uncertainties with two different classes can not be propagated.

exception lkdata.utils.uncertainty.MissingDataAssociationException

Bases: Exception

This exception should be used to indicate that an uncertainty instance has not been associated with a parent NDData object.

class lkdata.utils.uncertainty.NDUncertainty(array=None, copy=True)

Bases: object

This is the metaclass for uncertainty classes used with NDData.

Parameters:

arrayany type, optional

The array or value (the parameter name is due to historical reasons) of the uncertainty. numpy.ndarray or NDUncertainty subclasses are recommended. If the array is list-like or numpy.ndarray-like it will be cast to a plain numpy.ndarray. Default is None.

copybool, optional

Indicates whether to save the array as a copy. True copies it before saving, while False tries to save every parameter as reference. Note however that it is not always possible to save the input as reference. Default is True.

Raises:

IncompatibleUncertaintiesException

If given another NDUncertainty-like class as array if their uncertainty_type is different.

property array

numpy.ndarray : the uncertainty’s value.

property parent_nddata

NDData : reference to NDData instance with this uncertainty.

In case the reference is not set uncertainty propagation will not be possible since propagation might need the uncertain data besides the uncertainty.

propagate(operation, other_nddata, result_data, correlation, axis=None)

Calculate the resulting uncertainty given an operation on the data.

Parameters:

operationcallable

The operation that is performed on the NDData. Supported are numpy.add, numpy.subtract, numpy.multiply and numpy.true_divide (or numpy.divide).

other_nddataNDData instance

The second operand in the arithmetic operation.

result_datandarray

The result of the arithmetic operations on the data.

correlationnumpy.ndarray or number

The correlation (rho) is defined between the uncertainties in sigma_AB = sigma_A * sigma_B * rho. A value of 0 means uncorrelated operands.

axisint or tuple of ints, optional

Axis over which to perform a collapsing operation.

Returns:

resulting_uncertaintyNDUncertainty instance

Another instance of the same NDUncertainty subclass containing the uncertainty of the result.

Raises:

ValueError

If the operation is not supported or if correlation is not zero but the subclass does not support correlated uncertainties.

Notes

First this method checks if a correlation is given and the subclass implements propagation with correlated uncertainties. Then the second uncertainty is converted (or an Exception is raised) to the same class in order to do the propagation. Then the appropriate propagation method is invoked and the result is returned.

reshape(*args, **kwargs)

See NDUncertainty.array.reshape()

property shape

property supports_correlated

bool : Supports uncertainty propagation with correlated uncertainties?

abstract property uncertainty_type

str : Short description of the type of uncertainty.

Defined as abstract property so subclasses have to override this.

class lkdata.utils.uncertainty.Uncertainty(array=None, copy=True)

Bases: _VariancePropagationMixin, NDUncertainty

Standard deviation uncertainty assuming first order gaussian error propagation.

This class implements uncertainty propagation for addition, subtraction, multiplication and division with other instances of Uncertainty. Also support for correlation is possible but requires the correlation as input. It cannot handle correlation determination itself.

Parameters:

args, kwargs

see NDUncertainty

Examples

Uncertainty should always be associated with an NDData-like instance, either by creating it during initialization:

>>> from astropy.nddata import NDData, Uncertainty
>>> ndd = NDData([1,2,3],
...              uncertainty=Uncertainty([0.1, 0.1, 0.1]))
>>> ndd.uncertainty
Uncertainty([0.1, 0.1, 0.1])

or by setting it manually on the NDData instance:

>>> ndd.uncertainty = Uncertainty([0.2], copy=True)
>>> ndd.uncertainty
Uncertainty([0.2])

the uncertainty array can also be set directly:

>>> ndd.uncertainty.array = 2
>>> ndd.uncertainty
Uncertainty(2)

property supports_correlated

True : Uncertainty allows to propagate correlated uncertainties.

correlation must be given, this class does not implement computing it by itself.

property uncertainty_type

"std" : Uncertainty implements standard deviation.

Exceptions

Contains all lightkurve exceptions.

exception lkdata.utils.exceptions.LightkurveDeprecationWarning

Bases: LightkurveWarning

Class for all Lightkurve deprecation warnings.

exception lkdata.utils.exceptions.LightkurveError

Bases: Exception

Class for Lightkurve exceptions.

exception lkdata.utils.exceptions.LightkurveWarning

Bases: Warning

Class for all Lightkurve warnings.