threeML.utils package

Subpackages

Submodules

threeML.utils.bayesian_blocks module

threeML.utils.bayesian_blocks.bayesian_blocks(tt, ttstart, ttstop, p0, bkg_integral_distribution=None)[source]

Divide a series of events characterized by their arrival time in blocks of perceptibly constant count rate. If the background integral distribution is given, divide the series in blocks where the difference with respect to the background is perceptibly constant.

Parameters
  • tt – arrival times of the events

  • ttstart – the start of the interval

  • ttstop – the stop of the interval

  • p0 – the false positive probability. This is used to decide the penalization on the likelihood, so this

parameter affects the number of blocks :param bkg_integral_distribution: (default: None) If given, the algorithm account for the presence of the background and finds changes in rate with respect to the background :return: the np.array containing the edges of the blocks

threeML.utils.bayesian_blocks.bayesian_blocks_not_unique(tt, ttstart, ttstop, p0)[source]

threeML.utils.binner module

exception threeML.utils.binner.NotEnoughData[source]

Bases: RuntimeError

class threeML.utils.binner.Rebinner(vector_to_rebin_on, min_value_per_bin, mask=None)[source]

Bases: object

A class to rebin vectors keeping a minimum value per bin. It supports array with a mask, so that elements excluded through the mask will not be considered for the rebinning

get_new_start_and_stop(old_start, old_stop)[source]
property grouping
property n_bins

Returns the number of bins defined.

Returns

rebin(*vectors)[source]
rebin_errors(*vectors)[source]

Rebin errors by summing the squares

Args:

*vectors:

Returns:

array of rebinned errors

class threeML.utils.binner.TemporalBinner(list_of_intervals=())[source]

Bases: threeML.utils.time_interval.TimeIntervalSet

An extension of the TimeInterval set that includes binning capabilities

classmethod bin_by_bayesian_blocks(arrival_times, p0, bkg_integral_distribution=None)[source]

Divide a series of events characterized by their arrival time in blocks of perceptibly constant count rate. If the background integral distribution is given, divide the series in blocks where the difference with respect to the background is perceptibly constant.

Parameters
  • arrival_times – An iterable (list, numpy.array…) containing the arrival time of the events. NOTE: the input array MUST be time-ordered, and without duplicated entries. To ensure this, you may execute the following code: tt_array = numpy.asarray(self._arrival_times) tt_array = numpy.unique(tt_array) tt_array.sort() before running the algorithm.

  • p0 – The probability of finding a variations (i.e., creating a new block) when there is none. In other words, the probability of a Type I error, i.e., rejecting the null-hypothesis when is true. All found variations will have a post-trial significance larger than p0.

:param bkg_integral_distributionthe integral distribution for the

background counts. It must be a function of the form f(x), which must return the integral number of counts expected from the background component between time 0 and x.

classmethod bin_by_constant(arrival_times, dt)[source]

Create bins with a constant dt

Parameters

dt – temporal spacing of the bins

Returns

None

classmethod bin_by_custom(starts, stops)[source]

Simplicity function to make custom bins. This form keeps introduction of custom bins uniform for other binning methods

Parameters
  • start – start times of the bins

  • stop – stop times of the bins

Returns

classmethod bin_by_significance(arrival_times, background_getter, background_error_getter=None, sigma_level=10, min_counts=1, tstart=None, tstop=None)[source]

Bin the data to a given significance level for a given background method and sigma method. If a background error function is given then it is assumed that the error distribution is gaussian. Otherwise, the error distribution is assumed to be Poisson.

Parameters
  • background_getter – function of a start and stop time that returns background counts

  • background_error_getter – function of a start and stop time that returns background count errors

  • sigma_level – the sigma level of the intervals

  • min_counts – the minimum counts per bin

Returns

threeML.utils.cartesian module

threeML.utils.differentiation module

exception threeML.utils.differentiation.CannotComputeHessian[source]

Bases: RuntimeError

exception threeML.utils.differentiation.ParameterOnBoundary[source]

Bases: RuntimeError

threeML.utils.differentiation.get_hessian(function, point, minima, maxima)[source]
threeML.utils.differentiation.get_jacobian(function, point, minima, maxima)[source]

threeML.utils.fermi_relative_mission_time module

threeML.utils.fermi_relative_mission_time.compute_fermi_relative_mission_times(trigger_time)[source]

If the user has the requests library, this function looks online to the HEASARC xtime utility and computes other mission times relative to the input MET

Parameters

trigger_time – a fermi MET

Returns

mission time in a python dictionary

threeML.utils.histogram module

class threeML.utils.histogram.Histogram(list_of_intervals, contents=None, errors=None, sys_errors=None, is_poisson=False)[source]

Bases: threeML.utils.interval.IntervalSet

INTERVAL_TYPE

alias of threeML.utils.interval.Interval

bin_entries(entires)[source]

add the entries into the proper bin

Parameters

entires – list of events

Returns

property contents
display(fill=False, fill_min=0.0, x_label='x', y_label='y', **kwargs)[source]
property errors
classmethod from_entries(list_of_intervals, entries)[source]

create a histogram from a list of intervals and entries to bin

Parameters
  • list_of_intervals

  • entries

Returns

classmethod from_numpy_histogram(hist, errors=None, sys_errors=None, is_poisson=False, **kwargs)[source]

create a Histogram from a numpy histogram. Example:

r = np.random.randn(1000) np_hist = np.histogram(r) hist = Histogram.from_numpy_histogram(np_hist)

Parameters
  • hist – a np.histogram tuple

  • errors – list of errors for each bin in the numpy histogram

  • sys_errors – list of systematic errors for each bin in the numpy histogram

  • is_poisson – if the data is Poisson distributed or not

  • kwargs – any kwargs to pass along

Returns

a Histogram object

property is_poisson
property sys_errors
property total
property total_error

threeML.utils.interval module

class threeML.utils.interval.Interval(start: float, stop: float, swap_if_inverted: bool = False)[source]

Bases: object

intersect(interval: threeML.utils.interval.Interval)threeML.utils.interval.Interval[source]

Returns a new time interval corresponding to the intersection between this interval and the provided one.

Parameters

interval (Interval) – a TimeInterval instance

Returns

new interval covering the intersection

:raise IntervalsDoNotOverlap : if the intervals do not overlap

merge(interval: threeML.utils.interval.Interval)threeML.utils.interval.Interval[source]

Returns a new interval corresponding to the merge of the current and the provided time interval. The intervals must overlap.

Parameters

interval – a TimeInterval instance :type interval : Interval

Returns

a new TimeInterval instance

property mid_point
classmethod new(*args, **kwargs)[source]
overlaps_with(interval: threeML.utils.interval.Interval) → bool[source]

Returns whether the current time interval and the provided one overlap or not

Parameters

interval (Interval) – a TimeInterval instance

Returns

True or False

property start
property stop
to_string() → str[source]

returns a string representation of the time interval that is like the argument of many interval reading funcitons

Returns

class threeML.utils.interval.IntervalSet(list_of_intervals=())[source]

Bases: object

A set of intervals

INTERVAL_TYPE

alias of threeML.utils.interval.Interval

property absolute_start

the minimum of the start times :return:

property absolute_stop

the maximum of the stop times :return:

argsort()[source]

Returns the indices which order the set

Returns

property bin_stack
get a stacked view of the bins [[start_1,stop_1 ],

[start_2,stop_2 ]]

Returns

containing_bin(value)[source]

finds the index of the interval containing :param value: :return:

containing_interval(start, stop, inner=True, as_mask=False)[source]

returns either a mask of the intervals contained in the selection or a new set of intervals within the selection. NOTE: no sort is performed

Parameters
  • start – start of interval

  • stop – stop of interval

  • inner – if True, returns only intervals strictly contained within bounds, if False, returns outer bounds as well

  • as_mask – if you want a mask or the intervals

Returns

property edges

return an array of time edges if contiguous :return:

extend(list_of_intervals)[source]
classmethod from_list_of_edges(edges)[source]

Builds a IntervalSet from a list of time edges:

edges = [-1,0,1] -> [-1,0], [0,1]

Parameters

edges

Returns

classmethod from_starts_and_stops(starts, stops)[source]

Builds a TimeIntervalSet from a list of start and stop times:

start = [-1,0] -> [-1,0], [0,1] stop = [0,1]

Parameters
  • starts

  • stops

Returns

classmethod from_strings(*intervals)[source]

These are intervals specified as “-10 – 5”, “0-10”, and so on

Parameters

intervals

Returns

is_contiguous(relative_tolerance=1e-05)[source]

Check whether the time intervals are all contiguous, i.e., the stop time of one interval is the start time of the next

Returns

True or False

property is_sorted

Check whether the time intervals are sorted :return: True or False

merge_intersecting_intervals(in_place=False)[source]

merges intersecting intervals into a contiguous intervals

Returns

property mid_points
classmethod new(*args, **kwargs)[source]

Create a new interval set of this type :param args: :param kwargs: :return: interval set

classmethod new_interval(*args, **kwargs)[source]

Create a new interval of INTERVAL_TYPE :param args: :param kwargs: :return: interval

pop(index)[source]
sort()[source]

Returns a sorted copy of the set (sorted according to the tstart of the time intervals)

Returns

property starts

Return the starts fo the set

Returns

list of start times

property stops

Return the stops of the set

Returns

to_string()[source]

returns a set of string representaitons of the intervals :return:

property widths
exception threeML.utils.interval.IntervalsDoNotOverlap[source]

Bases: RuntimeError

exception threeML.utils.interval.IntervalsNotContiguous[source]

Bases: RuntimeError

threeML.utils.power_of_two_utils module

threeML.utils.power_of_two_utils.is_power_of_2(num)[source]

Returns whether num is a power of two or not :param num: an integer positive number :return: True if num is a power of 2, False otherwise

threeML.utils.power_of_two_utils.next_power_of_2(x)[source]

Returns the first power of two >= x, so f(2) = 2, f(127) = 128, f(65530) = 65536

Parameters

x

Returns

threeML.utils.step_parameter_generator module

threeML.utils.step_parameter_generator.step_generator(intervals, parameter)[source]

Generates sum of step or dirac delta functions for the given intervals and parameter. This can be used to link time-independent parameters of a model to time.

If the intervals provided are 1-D, i.e, they are the means of time bins or the TOA of photons, then a sum of dirac deltas is returned with their centers at the times provided

If the intervals are 2-D (start, stop), sum of step functions is created with the bounds at the start and stop times of the interval.

The parameter is used to set the bounds and initial value, min, max of the non-zero points of the functions

Parameters
  • intervals – an array of the 1- or 2-D intervals to be used

  • parameter – astromodels parameter

threeML.utils.string_utils module

threeML.utils.string_utils.dash_separated_string_to_tuple(arg)[source]

turn a dash separated string into a tuple

Parameters

arg – a dash separated string “a-b”

Returns

(a,b)

threeML.utils.time_interval module

class threeML.utils.time_interval.TimeInterval(start: float, stop: float, swap_if_inverted: bool = False)[source]

Bases: threeML.utils.interval.Interval

property duration
property half_time
property start_time
property stop_time
class threeML.utils.time_interval.TimeIntervalSet(list_of_intervals=())[source]

Bases: threeML.utils.interval.IntervalSet

A set of time intervals

INTERVAL_TYPE

alias of threeML.utils.time_interval.TimeInterval

property absolute_start_time

the minimum of the start times :return:

property absolute_stop_time

the maximum of the stop times :return:

display()[source]

Display the time intervals

Returns

None

property start_times

Return the starts fo the set

Returns

list of start times

property stop_times

Return the stops of the set

Returns

property time_edges

return an array of time edges if contiguous :return:

threeML.utils.unique_deterministic_tag module

threeML.utils.unique_deterministic_tag.get_unique_deterministic_tag(string)[source]

Return a hex string with a one to one correspondence with the given string

Parameters

string – a string

Returns

a hex unique digest

Module contents