pitchscapes.scapes.DiscretePitchScape_

class pitchscapes.scapes.DiscretePitchScape_(values, times=None, prior_counts=None, strategy='left', normalise=False, normalise_values=False, skip_type_check=False, dtype=None)

Bases: Scape

Discrete-time scape that is only well-defined at specific points in time. It computes the weighted sum (optionally the mean) over the given time window i.e. it sums up the values weighted by the corresponding time span and (optionally) divides by the total time interval.

Public Methods:

__init__(values[, times, prior_counts, ...])	Initialise the scape. :type values: :param values: values for each time slot (first dimension of size N runs over time intervals) :type times: :param times: [optional] boundaries of the time intervals (array like of length N+1). Defaults to [0, 1, ..., N]. :type prior_counts: :param prior_counts: scalar prior counts added to the aggregated values. Non-zero prior counts correspond to a Bayesian estimate with a uniform prior; the magnitude adjusts the prior strength. A value of None (default) does not add any prior counts. If return values are normalised (normalise=True) there is a difference between None and 0: A value of 0 is interpreted as the limitting case of non-zero prior counts, which means that outputs will always be normalised and if no data is available (zero counts, e.g. for zero-width time intervals or time intervals only zero values), a uniform distribution is returned. For a value of None, you will get an unnormalised all-zero output instead. :type strategy: :param strategy: one of ["left", "right", "center"] (default: "left"). Determines how a time-index interval [K, L] is split in the recursive computations. For "left": [K,L-1]+[L-1,L]; for "right": [K,K+1]+[K+1,L]; for "center": [K,K+1]+[K+1,L-1]+[L-1,L]. Also see comments for parse_bottom_up concerning efficiency and run time. :type normalise: :param normalise: whether to compute the weighted sum or mean (default: False i.e. compute weighted sum) :type normalise_values: :param normalise_values: whether to normalise the values per time interval (default: True) :type skip_type_check: :param skip_type_check: If the values are integers there may be problems with in-place normalisation or adding floating-type prior counts. The function raises a warning in these cases, suggesting to use a floating type for the values. This check can be disabled (which is generally a bad idea) by setting skip_type_check=True. Note that the warning is not raised for integer values of no normalisation is performed and the prior counts are None or not of a floating type. :type dtype: :param dtype: type to use for values.
assert_valid_time_window(start, end)
assert_valid_index_window(start, end)
__getitem__(item)	Return value of the scape at position :type item: :param item: (start, end) with start < end :return: value of the scape for the time window (start, end)
recursive_indices(start_idx, end_idx)
zero_size_value()
get_value_at_index(start, end)
add_prior_counts(value, delta_t)	Add prior counts ensuring correct normalisation.
parse_bottom_up()	Compute all values bottom up.

Inherited from Scape

__init__(min_time, max_time)
__getitem__(item)	Return value of the scape at position :type item: :param item: (start, end) with start < end :return: value of the scape for the time window (start, end)
assert_valid_time_window(start, end)

---

__annotations__ = {}

__dict__ = mappingproxy({'__module__': 'pitchscapes.scapes', '__doc__': '\n    Discrete-time scape that is only well-defined at specific points in time. It computes the weighted sum (optionally\n    the mean) over the given time window i.e. it sums up the values weighted by the corresponding time span and\n    (optionally) divides by the total time interval.\n    ', '__init__': <function DiscretePitchScape_.__init__>, 'assert_valid_time_window': <function DiscretePitchScape_.assert_valid_time_window>, 'assert_valid_index_window': <function DiscretePitchScape_.assert_valid_index_window>, '__getitem__': <function DiscretePitchScape_.__getitem__>, 'recursive_indices': <function DiscretePitchScape_.recursive_indices>, 'zero_size_value': <function DiscretePitchScape_.zero_size_value>, 'get_value_at_index': <function DiscretePitchScape_.get_value_at_index>, 'add_prior_counts': <function DiscretePitchScape_.add_prior_counts>, 'parse_bottom_up': <function DiscretePitchScape_.parse_bottom_up>, '__annotations__': {}})

__getitem__(item)

Return value of the scape at position :type item: :param item: (start, end) with start < end :return: value of the scape for the time window (start, end)

__init__(values, times=None, prior_counts=None, strategy='left', normalise=False, normalise_values=False, skip_type_check=False, dtype=None)

Initialise the scape. :type values: :param values: values for each time slot (first dimension of size N runs over time intervals) :type times: :param times: [optional] boundaries of the time intervals (array like of length N+1). Defaults to [0, 1, …, N]. :type prior_counts: :param prior_counts: scalar prior counts added to the aggregated values. Non-zero prior counts correspond to

a Bayesian estimate with a uniform prior; the magnitude adjusts the prior strength. A value of None (default) does not add any prior counts. If return values are normalised (normalise=True) there is a difference between None and 0: A value of 0 is interpreted as the limitting case of non-zero prior counts, which means that outputs will always be normalised and if no data is available (zero counts, e.g. for zero-width time intervals or time intervals only zero values), a uniform distribution is returned. For a value of None, you will get an unnormalised all-zero output instead.

Parameters:

strategy – one of [“left”, “right”, “center”] (default: “left”). Determines how a time-index interval

[K, L] is split in the recursive computations. For “left”: [K,L-1]+[L-1,L]; for “right”: [K,K+1]+[K+1,L]; for “center”: [K,K+1]+[K+1,L-1]+[L-1,L]. Also see comments for parse_bottom_up concerning efficiency and run time. :type normalise: :param normalise: whether to compute the weighted sum or mean (default: False i.e. compute weighted sum) :type normalise_values: :param normalise_values: whether to normalise the values per time interval (default: True) :type skip_type_check: :param skip_type_check: If the values are integers there may be problems with in-place normalisation or adding floating-type prior counts. The function raises a warning in these cases, suggesting to use a floating type for the values. This check can be disabled (which is generally a bad idea) by setting skip_type_check=True. Note that the warning is not raised for integer values of no normalisation is performed and the prior counts are None or not of a floating type. :type dtype: :param dtype: type to use for values

__module__ = 'pitchscapes.scapes'

__weakref__

list of weak references to the object (if defined)

add_prior_counts(value, delta_t)

Add prior counts ensuring correct normalisation. NOTE: value is modified in place.

assert_valid_index_window(start, end)

assert_valid_time_window(start, end)

get_value_at_index(start, end)

parse_bottom_up()

Compute all values bottom up. Performs an efficient dynamic programming pass through the entire scape and avoids time consuming recursive look-ups for compting single values (run time ~O(n^2)). This can be used if all values within the scape are expected to be needed. For high-resolution scapes where only few values need to be computed this may be inefficient as a single lookup has only ~O(n) run time. So if fewer than n values are needed, separate lookup will be more efficient. Moreover, if multiple value have the same start or end time, the overall run time for computing these values is only ~O(n). Depending on whether star or end time are in common the “left” or “right” strategy is more efficient.

recursive_indices(start_idx, end_idx)

zero_size_value()