trendminer.sdk.commons.interval module¶

class trendminer.sdk.commons.interval.Interval(start: datetime | str, is_open: bool = False, end: datetime | str | None = None, identifier: str | None = None)¶

Bases: ABC

An instance of type Interval structure.

start¶

Left bound for generating interval

Type:: datetime or str

end¶

Right bound for generating interval

Type:: datetime or str or optional

is_open¶

Whether the slice is open-ended

Type:: bool, optional, default False

identifier¶

Unique identifier to the object on the appliance.

Type:: str, optional

Example

interval1=client.time.interval("2021")
interval2=client.time.interval("2021-01-01 12:00:00", "2022")
interval3= client.time.interval("1h")

abstract after(duration: str, inplace: bool = False) → Interval¶

Get the interval after the current interval.

Parameters:

duration (str) – Value convertible into timedelta. Duration of the interval to be returned
inplace (bool, default False) – When True, no value is returned

Returns:

The interval after the current interval (when inplace=False)

Return type:

Interval or None

Example

interval = client.time.interval("2022-01-01 00:22:00", "2022-01-03 08:01:01")
print(interval.after("1h"))

abstract before(duration: str, inplace: bool = False) → Interval¶

Get the interval leading up to the current interval.

Parameters:

duration (str) – Value convertible into timedelta. Duration of the interval to be returned
inplace (bool, default False) – When True, no value is returned

Returns:

The interval before the current interval (when inplace=False)

Return type:

Interval or None

Example

interval = client.time.interval("2022-01-01 00:22:00", "2022-01-03 08:01:01")
print(interval.before("1h"))

abstract ceil(resolution: str, inplace: bool = False) → Interval¶

Round up start and end dates to the given resolution, potentially expanding the interval.

Parameters:

resolution (str) – The resolution to which all start and end dates will be rounded
inplace (bool, default False) – When True, no value is returned

Returns:

The interval which is rounded down to given resolution (expanding down the interval)

Return type:

Interval or None

Example

interval = client.time.interval("2022-01-01 12:10:23", "2022-01-03 08:01:01")
interval.ceil(resolution="1h",inplace=True)

print(f"Start: {interval.start}")
print(f"End: {interval.end}")

abstract property duration: timedelta¶

Duration of the Interval.

Returns:: The duration between start and end datetime
Return type:: timedelta

Example

interval = client.time.interval("2022-01-01 12:10:23", "2022-01-03 08:01:01")
print(f"duration: {interval.duration}")

abstract floor(resolution: str, inplace: bool = False) → Interval¶

Round down start and end dates to the given resolution, potentially narrowing down the interval.

Parameters:

resolution (str) – The resolution to which all start and end dates will be rounded
inplace (bool, default False) – When True, no value is returned

Returns:

The interval which is rounded down to given resolution (narrowing down the interval)

Return type:

Interval or None

Example

interval = client.time.interval("2022-01-01 12:10:23", "2022-01-03 08:01:01")
interval = interval.floor(resolution="1h")

print(f"Start: {interval.start}")
print(f"End: {interval.end}")

abstract shift(shift: str, inplace: bool = False) → Interval¶

Shift the interval.

Parameters:

shift (str) – Value convertible into timedelta. Shift of the interval
inplace (bool, default False) – When True, no value is returned

Returns:

The interval after the shift (when inplace=False)

Return type:

Interval or None

Example

interval = client.time.interval("9h")

print(f"Start: {interval.start}")
print(f"End: {interval.end}")

interval = interval.shift("-1h")

print(f"Start: {interval.start}")
print(f"End: {interval.end}")

abstract split(max_size: str) → Interval¶

Split the period into interval smaller or equal to the given size.

Parameters:: max_size (str) – Value convertible into timedelta. Maximal duration
Returns:: The interval after the split
Return type:: Interval or None

Example

interval = client.time.interval("2022-01-01 00:22:00", "2022-01-01 08:01:01")
interval.split("4h")

class trendminer.sdk.commons.interval.IntervalAPI¶

Bases: ABC

A class that provides user-friendly functions for interacting with Intervals.

abstract invert(intervals: list[trendminer.sdk.commons.interval.Interval], resolution: str | None = None, intervalspan: list[trendminer.sdk.commons.interval.Interval] | None = None) → list[trendminer.sdk.commons.interval.Interval]¶

Return intervals consisting of the time between the input intervals.

The output will always be sorted from oldest to newest intervals. Overlapping input intervals are not supported.

Parameters:

intervals (list of intervals) – List of intervals that need to be inverted
resolution (str, optional, default None) – The resolution to which all start and end dates will be rounded
intervalspan (Interval, optional) – Range over which the intervals need to be inverted. When given, the time from the start of the span to the start of the first input interval and the time from the last input interval to the end of the range are also returned as part of the inverted intervals, as long as they are not shorter than the index resolution (to avoid small intervals at the edges as a result of rounding). The intervalspan needs to encompass all input intervals. When no intervalspan is given, only the intervals inbetween the input intervals are returned as inverted intervals

Returns:

List of inverted intervals

Return type:

list

Example

search_interval = client.time.interval("2023-01-01 10:00", "2023-01-01 22:00")
included = [
    client.time.interval("2023-01-01 12:00", "2023-01-01 14:00"),
    client.time.interval("2023-01-01 18:00", "2023-01-01 20:00"),
]
excluded = client.time.interval.invert(included, intervalspan=search_interval)

list(intervals: tuple[str, str] | str | Interval)¶

Creates a list of Intervals from the given input values.

Parameters:: intervals (list of tuple or list of str or list of Interval or str or Interval or tuple) – Input to be converted into list of intervals. If input is a list (or similar), every item is converted. A single input is wrapped to become a list
Returns:: List of intervals
Return type:: list

Example

interval1=client.time.interval("2021")
interval2=client.time.interval("2021-01-01 12:00:00", "2022")
interval3= client.time.interval("1h")
interval1list=client.time.interval.list(["2021",("2021-01-01 12:00:00", "2022")])
interval1list2=client.time.interval.list([interval1,interval2,interval3])

Uses pandas.date_range to generate intervals with a fixed frequency.

Generates a range over the given timespan using pandas.data_range, and then converts those into intervals by taking iterating over the returned datetimes. The timezone given to date_range is always the client timezone. More info: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html

Note

Keep in mind that the returned intervals are always interlocking. For example, requesting business days (freq=’B’) will return a series of four 1-day intervals followed by a 3-day interval (Friday-Monday).

start¶

Left bound for generating intervals

Type:: str or datetime, optional

end¶

Right bound for generating intervals

Type:: str or datetime, optional

n_intervals¶

number of intervals to generate

Type:: int, optional

freq¶

Frequency strings can have multiples, e.g. ‘5H’. List of frequency aliases can be found here: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timeseries-offset-aliases

Type:: str or pandas.DateOffset, default ‘D’

normalize¶

Normalize start/end dates to midnight before generating date range

Type:: bool, default False

Returns:: List of Interval
Return type:: list

Example

# All full weeks (starting Monday) since the start of 2022, in client timezone

weeks = client.time.interval.range(start="2024-01-01 00:00:00",
                                    end=client.time.now(),
                                    freq="W-MON")

# Show first 4 weeks as example
weeks[0:4]

interval = client.time.interval("1W")
print(interval.start)
days = client.time.interval.range(start=interval.start, end=interval.end,
                                     freq="D", normalize=True)

abstract union(intervals: list[trendminer.sdk.commons.interval.Interval]) → list[trendminer.sdk.commons.interval.Interval]¶

Joins overlapping intervals together.

Parameters:: intervals (list of interval) – Potentially overlapping intervals
Returns:: Reduced non-overlapping list of intervals
Return type:: list

Example

interval1=client.time.interval("2021")
interval2=client.time.interval("2021-01-01 12:00:00", "2022")
interval3= client.time.interval("1h")
lll=client.time.interval.union([interval1,interval2,interval3])