anndata.ann.annlocation package

Submodules

anndata.ann.annlocation.disjoint module

filename

sppas.src.anndata.annlocation.disjoint.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Represent the disjoint interval localization of an annotation.

class anndata.ann.annlocation.disjoint.sppasDisjoint(intervals=None)

Bases: anndata.ann.annlocation.localization.sppasBaseLocalization

Localization of a serie of intervals in time.

__init__(intervals=None)

Create a new sppasDisjoint instance.

Parameters

intervals – (list of sppasInterval)

append_interval(interval)

Return the sppasInterval at the given index.

Parameters

interval – (sppasInterval)

copy()

Return a deep copy of self.

duration()

Return the sppasDuration.

Make the sum of all interval’ durations.

get_begin()

Return the first sppasPoint instance.

get_end()

Return the last sppasPoint instance.

get_interval(index)

Return the sppasInterval at the given index.

Parameters

index – (int)

get_intervals()

Return the list of intervals.

is_bound(point)

Return True if point is a bound of an interval.

is_disjoint()

Return True because self is representing a disjoint intervals.

middle()

Return a sppasPoint() at the middle of the time interval.

To be tested.

Returns

(sppasPoint)

set(other)

Set self members from another sppasDisjoint instance.

Parameters

other – (sppasDisjoint)

set_begin(tp)

Set the begin sppasPoint instance to new sppasPoint.

Parameters

tp – (sppasPoint)

set_end(tp)

Set the end sppasPoint instance to new sppasPoint.

Parameters

tp – (sppasPoint)

set_intervals(intervals)

Set a new list of intervals.

Parameters

intervals – list of sppasInterval.

set_radius(radius)

Set radius value to all points.

shift(delay)

Shift all the intervals to a given delay.

Parameters

delay – (int, float) delay to shift bounds

Raise

AnnDataTypeError

anndata.ann.annlocation.duration module

filename

sppas.src.anndata.annlocation.duration.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Represent a duration taking into account the radius of points.

class anndata.ann.annlocation.duration.sppasDuration(value, vagueness=0.0)

Bases: object

Representation of a duration with vagueness.

Represents a duration identified by 2 float values:

• the duration value;

• the duration margin.

__init__(value, vagueness=0.0)

Create a new sppasDuration instance.

Parameters

• value – (float) value of the duration.

• vagueness – (float) represents the vagueness of the value.

copy()

Return a deep copy of self.

get()

Return myself.

get_margin()

Return the vagueness of the duration (float).

get_value()

Return the duration value (float).

set(other)

Set the value/vagueness of another sppasDuration instance.

Parameters

other – (sppasDuration)

set_margin(vagueness)

Fix the vagueness margin of the duration.

Parameters

vagueness – (float) the duration margin.

set_value(value)

Set the duration to a new value.

Parameters

value – (float) the new duration value.

anndata.ann.annlocation.durationcompare module

filename

sppas.src.anndata.annlocation.durationcompare.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Comparison methods for durations, used by the filter system.

class anndata.ann.annlocation.durationcompare.sppasDurationCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for sppasDuration.

__init__()

Create a sppasDurationCompare instance.

static eq(duration, x)

Return True if duration is equal to x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static ge(duration, x)

Return True if duration is greater or equal than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static gt(duration, x)

Return True if duration is greater than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static le(duration, x)

Return True if duration is lower or equal than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static lt(duration, x)

Return True if duration is lower than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static ne(duration, x)

Return True if duration is different to x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

anndata.ann.annlocation.interval module

filename

sppas.src.anndata.annlocation.interval.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Represent the interval localization of an annotation.

class anndata.ann.annlocation.interval.sppasInterval(begin, end)

Bases: anndata.ann.annlocation.localization.sppasBaseLocalization

Localization of an interval between two sppasPoint instances.

An interval is identified by two sppasPoint objects:

• one is representing the beginning of the interval;

• the other is representing the end of the interval.

__init__(begin, end)

Create a new sppasInterval instance.

Parameters

• begin – (sppasPoint)

• end – (sppasPoint)

Degenerated interval is forbidden, i.e. begin > end.

static check_interval_bounds(begin, end)

Check bounds of a virtual interval.

Parameters

• begin – (sppasPoint)

• end – (sppasPoint)

static check_types(begin, end)

True only if begin and end are both the same types of sppasPoint.

Parameters

• begin – any kind of data

• end – any kind of data

Returns

Boolean

combine(other)

Return a sppasInterval, the combination of two intervals.

Parameters

other – (sppasInterval) the other interval to combine with.

copy()

Return a deep copy of self.

duration()

Overridden. Return the duration of the time interval.

Returns

(sppasDuration) Duration and its vagueness.

get_begin()

Return the begin sppasPoint instance.

get_end()

Return the end sppasPoint instance.

is_bound(point)

Return True if point is the begin or the end of the interval.

is_float()

is_int()

is_interval()

Overrides. Return True, because self represents an interval.

middle()

Return a sppasPoint() at the middle of the time interval.

To be tested.

Returns

(sppasPoint)

middle_value()

Return the middle value of the time interval.

Return a float value even if points are integers.

Returns

(float) value.

set(other)

Set self members from another sppasInterval instance.

Parameters

other – (sppasInterval)

set_begin(tp)

Set the begin of the interval to a new sppasPoint.

Attention: it is a reference assignment.

Parameters

tp – (sppasPoint)

set_end(tp)

Set the end of the interval to a new sppasPoint.

Attention: it is a reference assignment.

Parameters

tp – (sppasPoint)

set_radius(radius)

Set a radius value to begin and end points.

Parameters

radius – (int or float)

Raise

ValueError

shift(delay)

Shift the interval to a given delay.

Parameters

delay – (int, float) delay to shift bounds

Raise

AnnDataTypeError

union(other)

Return a sppasInterval representing the union of two intervals.

Parameters

other – (sppasInterval) the other interval to merge with.

anndata.ann.annlocation.intervalcompare module

filename

sppas.src.anndata.annlocation.intervalcompare.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Comparison methods of 2 intervals, used by the filter system.

This class is inspired by both the “Allen’s Interval Algebra” and INDU. James Allen, in 1983, proposed an algebraic framework named Interval Algebra (IA), for qualitative reasoning with time intervals where the binary relationship between a pair of intervals is represented by a subset of 13 atomic relation, that are:

• distinct because no pair of definite intervals can be related

by more than one of the relationships;

• exhaustive because any pair of definite intervals are described

by one of the relations;

• qualitative (rather than quantitative) because no numeric time

spans are considered.

These relations and the operations on them form the “Allen’s Interval Algebra”.

Using this calculus, given facts can be formalized and then used for automatic reasoning. Relations are: before, after, meets, met by, overlaps, overlapped by, starts, started by, finishes, finished by, contains, during and equals.

Pujari, Kumari and Sattar proposed INDU in 1999: an Interval & Duration network. They extended the IA to model qualitative information about intervals and durations in a single binary constraint network. Duration relations are: greater, lower and equal. INDU comprises of 25 basic relations between a pair of two intervals.

For convenience reasons, and because this class will be used to filter annotated data (and not reasoning), it implements the following methods:

‘before’ ‘before_equal’ ‘before_greater’ ‘before_lower’ ‘after’ ‘after_equal’ ‘after_greater’ ‘after_lower’ ‘meets’ ‘meets_equal’ ‘meets_greater’ ‘meets_lower’ ‘metby’ ‘metby_equal’ ‘metby_greater’ ‘metby_lower’ ‘overlaps’ ‘overlaps_equal’ ‘overlaps_greater’ ‘overlaps_lower’ ‘overlappedby’ ‘overlappedby_equal’ ‘overlappedby_greater’ ‘overlappedby_lower’ ‘starts’ ‘startedby’ ‘finishes’ ‘finishedby’ ‘contains’ ‘during’ ‘equals’

So that they are not distinct. Some of them accept parameters so they are not exhaustive too.

class anndata.ann.annlocation.intervalcompare.sppasIntervalCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

SPPAS implementation of interval’comparisons.

Includes “Allen’s Interval Algebra” and INDU, with several options. This class can be used to compare any of the localization-derived classes:

• sppasInterval(): begin and end points are used,

• sppasDisjoint(): the first and the last points are used and then it is considered a full interval.

• sppasPoint(): considered like a degenerated interval.

__init__()

Create a sppasIntervalCompare instance.

static after(i1, i2, max_delay=None, **kwargs)

Return True if i1 follows i2.

This is part of the Allen algebra.

Parameters

• i1 – |--------|

• i2 – |-------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i2 and the beginning of i1.

• **kwargs –

  unused.

static after_equal(i1, i2, *args)

static after_greater(i1, i2, *args)

static after_lower(i1, i2, *args)

static before(i1, i2, max_delay=None, **kwargs)

Return True if i1 precedes i2.

This is part of the Allen algebra.

Parameters

• i1 – |-------|

• i2 – |-------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

• **kwargs –

  un-used.

static before_equal(i1, i2, *args)

Return True if i1 precedes i2 and the durations are equals.

This is part of the INDU algebra.

Parameters

• i1 – |-------|

• i2 – |-------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

static before_greater(i1, i2, *args)

Return True if i1 precedes i2 and the duration of i1 is greater.

This is part of the INDU algebra.

Parameters

• i1 – |-----------|

• i2 – |-----|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

static before_lower(i1, i2, *args)

Return True if i1 precedes i2 and the duration of i1 is lower.

This is part of the INDU algebra.

Parameters

• i1 – |-----|

• i2 – |------------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

static contains(i1, i2, **kwargs)

Return True if i1 contains i2.

Parameters

• i1 – |------------|

• i2 – |----|

• **kwargs –

  unused.

static during(i1, i2, **kwargs)

Return True if i1 is located during i2.

Parameters

• i1 – |----|

• i2 – |------------|

• **kwargs –

  unused.

static equals(i1, i2, **kwargs)

Return True if i1 equals i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• **kwargs –

  unused.

static finishedby(i1, i2, **kwargs)

Return True if i1 finishes the same and starts before of i2.

Parameters

• i1 – |---------|

• i2 – |----|

• **kwargs –

  unused.

static finishes(i1, i2, **kwargs)

Return True if i1 finishes the same and starts within of i2.

Parameters

• i1 – |----|

• i2 – |---------|

• **kwargs –

  unused.

static meets(i1, i2, **kwargs)

Return True if i1 meets i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• **kwargs –

  unused.

static meets_equal(i1, i2, **kwargs)

static meets_greater(i1, i2, **kwargs)

static meets_lower(i1, i2, **kwargs)

static metby(i1, i2, **kwargs)

Return True if i1 is met by i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• **kwargs –

  unused.

static metby_equal(i1, i2, **kwargs)

static metby_greater(i1, i2, **kwargs)

static metby_lower(i1, i2, **kwargs)

static overlappedby(i1, i2, overlapped_min=None, percent=False, **kwargs)

Return True if i1 overlapped by i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• overlapped_min – (int/float/sppasDuration) Minimum duration of the overlap between i1 and i2.

• percent – (bool) The min_dur parameter is a percentage of i1, instead of an absolute duration.

• **kwargs –

  unused.

static overlappedby_equal(i1, i2, overlapped_min=None, percent=False, **kwargs)

static overlappedby_greater(i1, i2, overlapped_min=None, percent=False, **kwargs)

static overlappedby_lower(i1, i2, overlapped_min=None, percent=False, **kwargs)

static overlaps(i1, i2, overlap_min=None, percent=False, **kwargs)

Return True if i1 overlaps with i2.

Parameters

• i1 – |-------|

• i2 – |------|

• overlap_min – (int/float/sppasDuration) Minimum duration of the overlap between i1 and i2.

• percent – (bool) The min_dur parameter is a percentage of i1, instead of an absolute duration.

• **kwargs –

  unused.

static overlaps_equal(i1, i2, overlap_min=None, percent=False, **kwargs)

static overlaps_greater(i1, i2, overlap_min=None, percent=False, **kwargs)

static overlaps_lower(i1, i2, overlap_min=None, percent=False, **kwargs)

static startedby(i1, i2, **kwargs)

Return True if i1 is started at the start of i2 interval.

Parameters

• i1 – |----------|

• i2 – |----|

• **kwargs –

  unused.

static starts(i1, i2, **kwargs)

Return True if i1 starts at the start of i2 and finishes within it.

Parameters

• i1 – |----|

• i2 – |----------|

• **kwargs –

  unused.

anndata.ann.annlocation.localization module

filename

sppas.src.anndata.annlocation.localization.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

a base class to represent the localization of an annotation.

class anndata.ann.annlocation.localization.sppasBaseLocalization

Bases: object

Represents a base class for any kind of localization.

__init__()

Create a sppasLocalization instance.

copy()

Return a deep copy of self.

duration()

Return the duration of the localization.

Must be overridden

Returns

(sppasDuration) Duration and its vagueness.

get()

Return myself.

is_disjoint()

Return True if this object is an instance of sppasDisjoint.

Should be overridden.

is_interval()

Return True if this object is an instance of sppasInterval.

Should be overridden.

is_point()

Return True if this object is an instance of sppasPoint.

Should be overridden.

set(other)

Set self members from another localization.

Parameters

other – (sppasBaseLocalization)

set_radius(radius)

Set radius value to all points.

shift(delay)

Shift all the points to a given delay.

Parameters

delay – (int, float) delay to shift points

Raise

AnnDataTypeError

anndata.ann.annlocation.localizationcompare module

filename

sppas.src.anndata.annlocation.localizationcompare.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Comparison methods of 2 localizations, used by the filter system.

class anndata.ann.annlocation.localizationcompare.sppasLocalizationCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for sppasBaseLocalization.

__init__()

Create a sppasLocalizationCompare instance.

static rangefrom(localization, x)

Return True if localization is starting at x or after.

Parameters

• localization – (sppasBaseLocalization)

• x – (int, float, sppasPoint)

Returns

(bool)

static rangeto(localization, x)

Return True if localization is ending at x or before.

Parameters

• localization – (sppasBaseLocalization)

• x – (int, float, sppasPoint)

Returns

(bool)

anndata.ann.annlocation.location module

filename

sppas.src.anndata.annlocation.location.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Represent the list of possible localizations of an annotation.

class anndata.ann.annlocation.location.sppasLocation(localization=None, score=None)

Bases: object

Location of an annotation of a tier.

sppasLocation allows to store a set of localizations with their scores. This class is using a list of lists, i.e. a list of pairs (localization, score). This is the best compromise between memory usage, speed and readability.

__init__(localization=None, score=None)

Create a new sppasLocation instance and add the entry.

Parameters

• localization – (Localization or list of localizations)

• score – (float or list of float)

If a list of alternative localizations are given, the same score is assigned to all items.

append(localization, score=None)

Add a localization into the list.

Parameters

• localization – (Localization) the localization to append

• score – (float)

contains(point)

Return True if the localization point is in the list.

copy()

Return a deep copy of the location.

get_best()

Return a copy of the best localization.

Returns

(sppasLocalization) localization with the highest score.

get_highest_localization()

Return a copy of the sppasPoint with the highest loc.

get_lowest_localization()

Return a copy of the sppasPoint with the lowest localization.

get_score(loc)

Return the score of a localization or None if it is not in.

Parameters

loc – (sppasLocalization)

Returns

score: (float)

is_disjoint()

Return True if the location is made of sppasDisjoint locs.

is_interval()

Return True if the location is made of sppasInterval locs.

is_point()

Return True if the location is made of sppasPoint localizations.

match_duration(dur_functions, logic_bool='and')

Return True if a duration matches all or any of the functions.

Parameters

• dur_functions – list of (function, value, logical_not)

• logic_bool – (str) Apply a logical “and” or “or”

Returns

(bool)

• function: a function in python with 2 arguments: dur/value

• value: the expected value for the duration (int/float/sppasDuration)

• logical_not: boolean

Example

Search if a duration is exactly 30ms

>>> d.match([(eq, 0.03, False)])

Example

Search if a duration is not 30ms

>>> d.match([(eq, 0.03, True)])
>>> d.match([(ne, 0.03, False)])

Example

Search if a duration is comprised between 0.3 and 0.7 >>> l.match([(ge, 0.03, False), >>> (le, 0.07, False)], logic_bool=”and”)

See sppasDurationCompare() to get a list of functions.

match_localization(loc_functions, logic_bool='and')

Return True if a localization matches all or any of the functions.

Parameters

• loc_functions – list of (function, value, logical_not)

• logic_bool – (str) Apply a logical “and” or a logical “or”

between the functions. :returns: (bool)

• function: a function in python with 2 arguments: loc/value

• value: the expected value for the localization (int/float/sppasPoint)

• logical_not: boolean

Example

Search if a localization is after (or starts at) 1 minutes

>>> l.match([(rangefrom, 60., False)])

Example

Search if a localization is before (or ends at) 3 minutes

>>> l.match([(rangeto, 180., True)])

Example

Search if a localization is between 1 min and 3 min

>>> l.match([(rangefrom, 60., False),
>>>          (rangeto, 180., False)], logic_bool="and")

See sppasLocalizationCompare() to get a list of functions.

remove(localization)

Remove a localization of the list.

Parameters

localization – (sppasLocalization) the loc to be removed

set_radius(radius)

Set a radius value to all localizations.

Parameters

radius – (int, float) New radius value

Raise

AnnDataTypeError, AnnDataNegValueError

set_score(loc, score)

Set a score to a given localization.

Parameters

• loc – (sppasLocalization)

• score – (float)

shift(delay)

Shift the location to a given delay.

Parameters

delay – (int, float) delay to shift all localizations

Raise

AnnDataTypeError

anndata.ann.annlocation.point module

filename

sppas.src.anndata.annlocation.point.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

Represent a point made of a midpoint and a radius.

class anndata.ann.annlocation.point.sppasPoint(midpoint, radius=None)

Bases: anndata.ann.annlocation.localization.sppasBaseLocalization

Localization of a point for any numerical representation.

Represents a point identified by a midpoint value and a radius value. Generally, time is represented in seconds, as a float value ; frames are represented by integers like ranks.

In this class, the 3 relations <, = and > take into account a radius value, that represents the uncertainty of the localization. For a point x, with a radius value of rx, and a point y with a radius value of ry, these relations are defined as:

• x = y iff |x - y| <= rx + ry

• x < y iff not(x = y) and x < y

• x > y iff not(x = y) and x > y

Example 1

Strictly equals:

• x = 1.000, rx=0.

• y = 1.000, ry=0.

• x = y is true

• x = 1.00000000000, rx=0.

• y = 0.99999999675, ry=0.

• x = y is false

Example 2

Using the radius:

• x = 1.0000000000, rx=0.0005

• y = 1.0000987653, ry=0.0005

• x = y is true (accepts a margin of 1ms between x and y)

• x = 1.0000000, rx=0.0005

• y = 1.0011235, ry=0.0005

• x = y is false

So… an overlap of the vagueness “area” makes the two points equals: |------------rx----------X-----ry===rx----Y--------ry------|

__init__(midpoint, radius=None)

Create a sppasPoint instance.

Parameters

• midpoint – (float, int) midpoint value.

• radius – (float, int) represents the vagueness of the point.

Radius must be of the same type as midpoint.

static check_types(x, y)

True only if midpoint and radius are both of the same types.

Parameters

• x – any kind of data

• y – any kind of data

Returns

Boolean

copy()

Return a deep copy of self.

duration()

Overrides. Return the duration of the point.

Returns

(sppasDuration) Duration and its vagueness.

get_midpoint()

Return the midpoint value.

get_radius()

Return the radius value (float or None).

is_float()

Return True if the value of the point is a float.

is_int()

Return True if the value of the point is an integer.

is_point()

Override. Return True, because self represents a point.

set(other)

Set self members from another sppasPoint instance.

Parameters

other – (sppasPoint)

set_midpoint(midpoint)

Set the midpoint value.

In versions < 1.9.8, it was required that midpoint >= 0. Negative values are now accepted because some annotations are not properly synchronized and then some of them can be negative.

Parameters

midpoint – (float, int) is the new midpoint value.

Raise

AnnDataTypeError

set_radius(radius=None)

Fix the radius value, ie. the vagueness of the point.

The midpoint value must be set first.

Parameters

radius – (float, int, None) the radius value

Raise

AnnDataTypeError, AnnDataNegValueError

shift(delay)

Shift the point to a given delay.

Parameters

delay – (int, float) delay to shift midpoint

Raise

AnnDataTypeError

Module contents

filename

sppas.src.anndata.annlocation.__init__.py

author

Brigitte Bigi

contact

develop@sppas.org

summary

the anchor in time of an annotation.

class anndata.ann.annlocation.sppasBaseLocalization

Bases: object

Represents a base class for any kind of localization.

__init__()

Create a sppasLocalization instance.

copy()

Return a deep copy of self.

duration()

Return the duration of the localization.

Must be overridden

Returns

(sppasDuration) Duration and its vagueness.

get()

Return myself.

is_disjoint()

Return True if this object is an instance of sppasDisjoint.

Should be overridden.

is_interval()

Return True if this object is an instance of sppasInterval.

Should be overridden.

is_point()

Return True if this object is an instance of sppasPoint.

Should be overridden.

set(other)

Set self members from another localization.

Parameters

other – (sppasBaseLocalization)

set_radius(radius)

Set radius value to all points.

shift(delay)

Shift all the points to a given delay.

Parameters

delay – (int, float) delay to shift points

Raise

AnnDataTypeError

class anndata.ann.annlocation.sppasDisjoint(intervals=None)

Bases: anndata.ann.annlocation.localization.sppasBaseLocalization

Localization of a serie of intervals in time.

__init__(intervals=None)

Create a new sppasDisjoint instance.

Parameters

intervals – (list of sppasInterval)

append_interval(interval)

Return the sppasInterval at the given index.

Parameters

interval – (sppasInterval)

copy()

Return a deep copy of self.

duration()

Return the sppasDuration.

Make the sum of all interval’ durations.

get_begin()

Return the first sppasPoint instance.

get_end()

Return the last sppasPoint instance.

get_interval(index)

Return the sppasInterval at the given index.

Parameters

index – (int)

get_intervals()

Return the list of intervals.

is_bound(point)

Return True if point is a bound of an interval.

is_disjoint()

Return True because self is representing a disjoint intervals.

middle()

Return a sppasPoint() at the middle of the time interval.

To be tested.

Returns

(sppasPoint)

set(other)

Set self members from another sppasDisjoint instance.

Parameters

other – (sppasDisjoint)

set_begin(tp)

Set the begin sppasPoint instance to new sppasPoint.

Parameters

tp – (sppasPoint)

set_end(tp)

Set the end sppasPoint instance to new sppasPoint.

Parameters

tp – (sppasPoint)

set_intervals(intervals)

Set a new list of intervals.

Parameters

intervals – list of sppasInterval.

set_radius(radius)

Set radius value to all points.

shift(delay)

Shift all the intervals to a given delay.

Parameters

delay – (int, float) delay to shift bounds

Raise

AnnDataTypeError

class anndata.ann.annlocation.sppasDuration(value, vagueness=0.0)

Bases: object

Representation of a duration with vagueness.

Represents a duration identified by 2 float values:

• the duration value;

• the duration margin.

__init__(value, vagueness=0.0)

Create a new sppasDuration instance.

Parameters

• value – (float) value of the duration.

• vagueness – (float) represents the vagueness of the value.

copy()

Return a deep copy of self.

get()

Return myself.

get_margin()

Return the vagueness of the duration (float).

get_value()

Return the duration value (float).

set(other)

Set the value/vagueness of another sppasDuration instance.

Parameters

other – (sppasDuration)

set_margin(vagueness)

Fix the vagueness margin of the duration.

Parameters

vagueness – (float) the duration margin.

set_value(value)

Set the duration to a new value.

Parameters

value – (float) the new duration value.

class anndata.ann.annlocation.sppasDurationCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for sppasDuration.

__init__()

Create a sppasDurationCompare instance.

static eq(duration, x)

Return True if duration is equal to x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static ge(duration, x)

Return True if duration is greater or equal than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static gt(duration, x)

Return True if duration is greater than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static le(duration, x)

Return True if duration is lower or equal than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static lt(duration, x)

Return True if duration is lower than x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

static ne(duration, x)

Return True if duration is different to x.

Parameters

• duration – (sppasDuration)

• x – (int, float)

Returns

(bool)

class anndata.ann.annlocation.sppasInterval(begin, end)

Bases: anndata.ann.annlocation.localization.sppasBaseLocalization

Localization of an interval between two sppasPoint instances.

An interval is identified by two sppasPoint objects:

• one is representing the beginning of the interval;

• the other is representing the end of the interval.

__init__(begin, end)

Create a new sppasInterval instance.

Parameters

• begin – (sppasPoint)

• end – (sppasPoint)

Degenerated interval is forbidden, i.e. begin > end.

static check_interval_bounds(begin, end)

Check bounds of a virtual interval.

Parameters

• begin – (sppasPoint)

• end – (sppasPoint)

static check_types(begin, end)

True only if begin and end are both the same types of sppasPoint.

Parameters

• begin – any kind of data

• end – any kind of data

Returns

Boolean

combine(other)

Return a sppasInterval, the combination of two intervals.

Parameters

other – (sppasInterval) the other interval to combine with.

copy()

Return a deep copy of self.

duration()

Overridden. Return the duration of the time interval.

Returns

(sppasDuration) Duration and its vagueness.

get_begin()

Return the begin sppasPoint instance.

get_end()

Return the end sppasPoint instance.

is_bound(point)

Return True if point is the begin or the end of the interval.

is_float()

is_int()

is_interval()

Overrides. Return True, because self represents an interval.

middle()

Return a sppasPoint() at the middle of the time interval.

To be tested.

Returns

(sppasPoint)

middle_value()

Return the middle value of the time interval.

Return a float value even if points are integers.

Returns

(float) value.

set(other)

Set self members from another sppasInterval instance.

Parameters

other – (sppasInterval)

set_begin(tp)

Set the begin of the interval to a new sppasPoint.

Attention: it is a reference assignment.

Parameters

tp – (sppasPoint)

set_end(tp)

Set the end of the interval to a new sppasPoint.

Attention: it is a reference assignment.

Parameters

tp – (sppasPoint)

set_radius(radius)

Set a radius value to begin and end points.

Parameters

radius – (int or float)

Raise

ValueError

shift(delay)

Shift the interval to a given delay.

Parameters

delay – (int, float) delay to shift bounds

Raise

AnnDataTypeError

union(other)

Return a sppasInterval representing the union of two intervals.

Parameters

other – (sppasInterval) the other interval to merge with.

class anndata.ann.annlocation.sppasIntervalCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

SPPAS implementation of interval’comparisons.

Includes “Allen’s Interval Algebra” and INDU, with several options. This class can be used to compare any of the localization-derived classes:

• sppasInterval(): begin and end points are used,

• sppasDisjoint(): the first and the last points are used and then it is considered a full interval.

• sppasPoint(): considered like a degenerated interval.

__init__()

Create a sppasIntervalCompare instance.

static after(i1, i2, max_delay=None, **kwargs)

Return True if i1 follows i2.

This is part of the Allen algebra.

Parameters

• i1 – |--------|

• i2 – |-------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i2 and the beginning of i1.

• **kwargs –

  unused.

static after_equal(i1, i2, *args)

static after_greater(i1, i2, *args)

static after_lower(i1, i2, *args)

static before(i1, i2, max_delay=None, **kwargs)

Return True if i1 precedes i2.

This is part of the Allen algebra.

Parameters

• i1 – |-------|

• i2 – |-------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

• **kwargs –

  un-used.

static before_equal(i1, i2, *args)

Return True if i1 precedes i2 and the durations are equals.

This is part of the INDU algebra.

Parameters

• i1 – |-------|

• i2 – |-------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

static before_greater(i1, i2, *args)

Return True if i1 precedes i2 and the duration of i1 is greater.

This is part of the INDU algebra.

Parameters

• i1 – |-----------|

• i2 – |-----|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

static before_lower(i1, i2, *args)

Return True if i1 precedes i2 and the duration of i1 is lower.

This is part of the INDU algebra.

Parameters

• i1 – |-----|

• i2 – |------------|

• max_delay – (int/float/sppasDuration) Maximum delay between the end of i1 and the beginning of i2.

static contains(i1, i2, **kwargs)

Return True if i1 contains i2.

Parameters

• i1 – |------------|

• i2 – |----|

• **kwargs –

  unused.

static during(i1, i2, **kwargs)

Return True if i1 is located during i2.

Parameters

• i1 – |----|

• i2 – |------------|

• **kwargs –

  unused.

static equals(i1, i2, **kwargs)

Return True if i1 equals i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• **kwargs –

  unused.

static finishedby(i1, i2, **kwargs)

Return True if i1 finishes the same and starts before of i2.

Parameters

• i1 – |---------|

• i2 – |----|

• **kwargs –

  unused.

static finishes(i1, i2, **kwargs)

Return True if i1 finishes the same and starts within of i2.

Parameters

• i1 – |----|

• i2 – |---------|

• **kwargs –

  unused.

static meets(i1, i2, **kwargs)

Return True if i1 meets i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• **kwargs –

  unused.

static meets_equal(i1, i2, **kwargs)

static meets_greater(i1, i2, **kwargs)

static meets_lower(i1, i2, **kwargs)

static metby(i1, i2, **kwargs)

Return True if i1 is met by i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• **kwargs –

  unused.

static metby_equal(i1, i2, **kwargs)

static metby_greater(i1, i2, **kwargs)

static metby_lower(i1, i2, **kwargs)

static overlappedby(i1, i2, overlapped_min=None, percent=False, **kwargs)

Return True if i1 overlapped by i2.

Parameters

• i1 – |-------|

• i2 – |-------|

• overlapped_min – (int/float/sppasDuration) Minimum duration of the overlap between i1 and i2.

• percent – (bool) The min_dur parameter is a percentage of i1, instead of an absolute duration.

• **kwargs –

  unused.

static overlappedby_equal(i1, i2, overlapped_min=None, percent=False, **kwargs)

static overlappedby_greater(i1, i2, overlapped_min=None, percent=False, **kwargs)

static overlappedby_lower(i1, i2, overlapped_min=None, percent=False, **kwargs)

static overlaps(i1, i2, overlap_min=None, percent=False, **kwargs)

Return True if i1 overlaps with i2.

Parameters

• i1 – |-------|

• i2 – |------|

• overlap_min – (int/float/sppasDuration) Minimum duration of the overlap between i1 and i2.

• percent – (bool) The min_dur parameter is a percentage of i1, instead of an absolute duration.

• **kwargs –

  unused.

static overlaps_equal(i1, i2, overlap_min=None, percent=False, **kwargs)

static overlaps_greater(i1, i2, overlap_min=None, percent=False, **kwargs)

static overlaps_lower(i1, i2, overlap_min=None, percent=False, **kwargs)

static startedby(i1, i2, **kwargs)

Return True if i1 is started at the start of i2 interval.

Parameters

• i1 – |----------|

• i2 – |----|

• **kwargs –

  unused.

static starts(i1, i2, **kwargs)

Return True if i1 starts at the start of i2 and finishes within it.

Parameters

• i1 – |----|

• i2 – |----------|

• **kwargs –

  unused.

class anndata.ann.annlocation.sppasLocalizationCompare

Bases: sppas.src.structs.basecompare.sppasBaseCompare

Comparison methods for sppasBaseLocalization.

__init__()

Create a sppasLocalizationCompare instance.

static rangefrom(localization, x)

Return True if localization is starting at x or after.

Parameters

• localization – (sppasBaseLocalization)

• x – (int, float, sppasPoint)

Returns

(bool)

static rangeto(localization, x)

Return True if localization is ending at x or before.

Parameters

• localization – (sppasBaseLocalization)

• x – (int, float, sppasPoint)

Returns

(bool)

class anndata.ann.annlocation.sppasLocation(localization=None, score=None)

Bases: object

Location of an annotation of a tier.

sppasLocation allows to store a set of localizations with their scores. This class is using a list of lists, i.e. a list of pairs (localization, score). This is the best compromise between memory usage, speed and readability.

__init__(localization=None, score=None)

Create a new sppasLocation instance and add the entry.

Parameters

• localization – (Localization or list of localizations)

• score – (float or list of float)

If a list of alternative localizations are given, the same score is assigned to all items.

append(localization, score=None)

Add a localization into the list.

Parameters

• localization – (Localization) the localization to append

• score – (float)

contains(point)

Return True if the localization point is in the list.

copy()

Return a deep copy of the location.

get_best()

Return a copy of the best localization.

Returns

(sppasLocalization) localization with the highest score.

get_highest_localization()

Return a copy of the sppasPoint with the highest loc.

get_lowest_localization()

Return a copy of the sppasPoint with the lowest localization.

get_score(loc)

Return the score of a localization or None if it is not in.

Parameters

loc – (sppasLocalization)

Returns

score: (float)

is_disjoint()

Return True if the location is made of sppasDisjoint locs.

is_interval()

Return True if the location is made of sppasInterval locs.

is_point()

Return True if the location is made of sppasPoint localizations.

match_duration(dur_functions, logic_bool='and')

Return True if a duration matches all or any of the functions.

Parameters

• dur_functions – list of (function, value, logical_not)

• logic_bool – (str) Apply a logical “and” or “or”

Returns

(bool)

• function: a function in python with 2 arguments: dur/value

• value: the expected value for the duration (int/float/sppasDuration)

• logical_not: boolean

Example

Search if a duration is exactly 30ms

>>> d.match([(eq, 0.03, False)])

Example

Search if a duration is not 30ms

>>> d.match([(eq, 0.03, True)])
>>> d.match([(ne, 0.03, False)])

Example

Search if a duration is comprised between 0.3 and 0.7 >>> l.match([(ge, 0.03, False), >>> (le, 0.07, False)], logic_bool=”and”)

See sppasDurationCompare() to get a list of functions.

match_localization(loc_functions, logic_bool='and')

Return True if a localization matches all or any of the functions.

Parameters

• loc_functions – list of (function, value, logical_not)

• logic_bool – (str) Apply a logical “and” or a logical “or”

between the functions. :returns: (bool)

• function: a function in python with 2 arguments: loc/value

• value: the expected value for the localization (int/float/sppasPoint)

• logical_not: boolean

Example

Search if a localization is after (or starts at) 1 minutes

>>> l.match([(rangefrom, 60., False)])

Example

Search if a localization is before (or ends at) 3 minutes

>>> l.match([(rangeto, 180., True)])

Example

Search if a localization is between 1 min and 3 min

>>> l.match([(rangefrom, 60., False),
>>>          (rangeto, 180., False)], logic_bool="and")

See sppasLocalizationCompare() to get a list of functions.

remove(localization)

Remove a localization of the list.

Parameters

localization – (sppasLocalization) the loc to be removed

set_radius(radius)

Set a radius value to all localizations.

Parameters

radius – (int, float) New radius value

Raise

AnnDataTypeError, AnnDataNegValueError

set_score(loc, score)

Set a score to a given localization.

Parameters

• loc – (sppasLocalization)

• score – (float)

shift(delay)

Shift the location to a given delay.

Parameters

delay – (int, float) delay to shift all localizations

Raise

AnnDataTypeError

class anndata.ann.annlocation.sppasPoint(midpoint, radius=None)

Bases: anndata.ann.annlocation.localization.sppasBaseLocalization

Localization of a point for any numerical representation.

Represents a point identified by a midpoint value and a radius value. Generally, time is represented in seconds, as a float value ; frames are represented by integers like ranks.

In this class, the 3 relations <, = and > take into account a radius value, that represents the uncertainty of the localization. For a point x, with a radius value of rx, and a point y with a radius value of ry, these relations are defined as:

• x = y iff |x - y| <= rx + ry

• x < y iff not(x = y) and x < y

• x > y iff not(x = y) and x > y

Example 1

Strictly equals:

• x = 1.000, rx=0.

• y = 1.000, ry=0.

• x = y is true

• x = 1.00000000000, rx=0.

• y = 0.99999999675, ry=0.

• x = y is false

Example 2

Using the radius:

• x = 1.0000000000, rx=0.0005

• y = 1.0000987653, ry=0.0005

• x = y is true (accepts a margin of 1ms between x and y)

• x = 1.0000000, rx=0.0005

• y = 1.0011235, ry=0.0005

• x = y is false

So… an overlap of the vagueness “area” makes the two points equals: |------------rx----------X-----ry===rx----Y--------ry------|

__init__(midpoint, radius=None)

Create a sppasPoint instance.

Parameters

• midpoint – (float, int) midpoint value.

• radius – (float, int) represents the vagueness of the point.

Radius must be of the same type as midpoint.

static check_types(x, y)

True only if midpoint and radius are both of the same types.

Parameters

• x – any kind of data

• y – any kind of data

Returns

Boolean

copy()

Return a deep copy of self.

duration()

Overrides. Return the duration of the point.

Returns

(sppasDuration) Duration and its vagueness.

get_midpoint()

Return the midpoint value.

get_radius()

Return the radius value (float or None).

is_float()

Return True if the value of the point is a float.

is_int()

Return True if the value of the point is an integer.

is_point()

Override. Return True, because self represents a point.

set(other)

Set self members from another sppasPoint instance.

Parameters

other – (sppasPoint)

set_midpoint(midpoint)

Set the midpoint value.

In versions < 1.9.8, it was required that midpoint >= 0. Negative values are now accepted because some annotations are not properly synchronized and then some of them can be negative.

Parameters

midpoint – (float, int) is the new midpoint value.

Raise

AnnDataTypeError

set_radius(radius=None)

Fix the radius value, ie. the vagueness of the point.

The midpoint value must be set first.

Parameters

radius – (float, int, None) the radius value

Raise

AnnDataTypeError, AnnDataNegValueError

shift(delay)

Shift the point to a given delay.

Parameters

delay – (int, float) delay to shift midpoint

Raise

AnnDataTypeError