Organizer class¶

class timeboard.Organizer(marker=None, marks=None, structure=None)¶

Specification of timeline’s layout.

Organizer contains rules which define the transformation of a timeboard’s reference frame into a timeline of workshifts. There are two phases in this process. Firstly, the frame is partitioned into chunks called spans. Secondly, workshifts of each span receive labels according to some labeling pattern.

Spans begin on base units referred to by points in time called marks. The locations of the marks are defined in Organizer by either marker or marks parameter.

Given marker parameter, marks are computed according to the rules set by a Marker passed as the value of marker.

If marks parameter is provided instead, it is interpreted as a list of explicitly specified points in time which will serve as marks.

One and only one of marker or marks parameters must be supplied.

The second parameter of Organizer, structure, tells how to organize the spans. structure is an iterable and its elements are mapped onto the spans: the first element of structure is applied to the first span, the second element - to the second span, and so on.

Each element of structure must be one of the following:

another Organizer,
a pattern (an iterable of workshift labels),
a single label.

If an element of structure is an Organizer, it is used to recursively partition this span into sub-spans.

Pattern is an iterable of workshift labels, such as an explicit list of labels, or an iterator, such as an instance of RememberingPattern. If an element of structure is a pattern, each base unit of the span becomes a workshift. The labels for these workshifts are taken from the pattern. If the pattern is empty, the workshifts of the span retain the default labeling of the timeline.

If an element of structure is some other single value, it is considered a label. In this case, the whole span becomes a single workshift which receives this label. Such a compound workshift comprises several base units (unless the span itself consists of a single base unit).

Once structure is exhausted but there are untreated spans remaining, structure is re-enacted in cycles. The same approach applies to patterns producing workshift labels.

If structure is empty, no organizing occurs. The timeline retains the default label for every workshift and workshifts coincide with base units.

Parameters:

marker : Marker or str

If a string is given, it must be a pandas-compatible calendar frequency (accepts the same kind of values as base_unit_freq of timeboard). Under the hood marker=freq is silently converted to marker=Marker(each=freq).

marks : Iterable of Timestamp-like

Parameters marker and marks are mutually exclusive.

structure : Iterable

An element of structure may be one of the following:

an Organizer,

a pattern (iterable or iterator of labels),

a single label.

A RememberingPattern may be used both as an element of structure or as an entire structure.

Raises:

ValueError: If both marker and marks are specified.

Marker class¶

class timeboard.Marker(each, at=None, how='from_start_of_each')¶

Specification of markup of a timeboard’s frame.

Markup is an ordered sequence of marks placed at calculated points in time within some span being a part of a frame or an entire frame. Marks are produced by an algorithm defined by attributes of a Marker.

In each calendar period of frequency each located partly or entirely within the span the algorithm finds points in time defined by at parameter which is a list of dictionaries.

Each dictionary in at list is a collection of keyword arguments; it defines a point in time. Hence, the number of points sought in each each period is equal to the length of at list.

The interpretation of at keywords by the algorithm is defined by parameter how.

Value of how	Interpretation of keyword arguments in at
‘from_start_of_each’	Keyword arguments define an offset from the beginning of each period. Acceptable keyword arguments are `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'months'`, `'years'`. Example: `at=[{'days':0}, {'days':1, 'hours':2}]` (the first mark is at the start of the period, the second is in 1 day and 2 hours from the start of the period).
‘from_easter_western’	Keyword arguments define an offset from the day of Western Easter. Acceptable arguments are the same as above.
‘from_easter_orthodox’	Keyword arguments define an offset from the day of Orthodox Easter. Acceptable arguments are the same as above.
‘nth_weekday_of_month’	Keywords arguments refer to N-th weekday of M-th month from the start of each period. Acceptable keywords are: `'month'` : 1..12 1 is for the first month (such as January for annual periods). `'weekday'` : 1..7 1 is for Monday, 7 is for Sunday. `'week'` : -5..-1, 1..5 -1 is for the last and 1 is for the first occurrence of the weekday in the month. Zero is not allowed. `'shift'` : int, optional, default 0 An offset in days from the weekday found. Example: `at=[{'month':5, 'weekday':7, 'week':-1}]` (the last Sunday of the 5th month)

The location of every point in time which has been calculated by the above procedure is inspected. If it is within the each period in which it was being sought and within the span, the point becomes a mark. Otherwise, it is ignored.

If at parameter is not provided or at list is empty, the marks are set on the start times of calendar periods specified by each.

Organizer uses markup defined by Marker to partition the frame into spans. The first span always starts on the first base unit of the frame. The second span starts on the base unit which contains the first mark. The last span starts on the base unit containing the last mark and ends on the last base unit of the span. If no marks have been set, only one span is created which contains the entire frame.

Parameters:

each : str

pandas-compatible calendar frequency; accepts the same values as base_unit_freq of timeboard.

at : list of dict, optional

Each dictionary is a collection of keyword arguments interpreted by parameter how.

how : str or function, optional

Acceptable string values:

'from_start_of_each' : (default)

Keyword arguments in at define an offset (number of hours, days, etc.) from the start of each period.
'from_easter_western' :

Keyword arguments in at define an offset from the Western Easter in each period.
'from_easter_orthodox' :

Keyword arguments in at define an offset from the Orthodox Easter in each period.
'nth_weekday_of_month' :

Keyword arguments in at define N-th weekday of M-th month from the start of each period.

Notes

A string passed as the value of how is effectively substituted by its namesake function from module timeboard.when.

Alternatively, a user-defined function may be supplied as the value of how. The function must conform to the signature:

function(periods: pandas.PeriodIndex, 
         normalize_by: str, **kwargs) -> pandas.DatetimeIndex

This function is called once for each element of at list. It will receive the series of all each periods of the span in periods parameter, base_unit_freq in normalize_by and a collection of keyword arguments constituting the currently processed element of at. The function is expected to return a series of points in time.

Examples

Mark a span by weeks (set a mark on each Monday at 00:00):

>>> tb.Marker(each='W')

Set a mark on each Wednesday and each Saturday at 00:00. Note that there is no mark on Monday because now at list is not empty but Monday is not explicitly specified in the list.

>>> tb.Marker(each='W', at=[{'days': 2}, {'days': 5}]) 

Set a mark on each Monday, Wednesday, and Saturday at 00:00:

>>> tb.Marker(each='W', at=[{'days': 0}, {'days': 2}, {'days': 5}])

No marks will be set in the following example. Adding 7 days to the start of the week places the candidate point into the next week, i.e. outside the current each period, hence this point is not a valid mark.

>>> tb.Marker(each='W', at=[{'days': 7}])

Mark a span by days (set a mark at each midnight):

>>> tb.Marker(each='D')

Set marks at 09:00 and 18:00 on each day (but not at the midnight):

>>> tb.Marker(each='D', at=[{'hours': 9}, {'hours':18}])

Set a mark on the beginning of the 31st day of each month. If there is no 31st day, there will be no mark in this month. For example, if the span is a calendar year, marks will be set on Jan 31, Mar 31, May 31, Jul 31, Aug 31, Oct 31, and Dec 31:

>>> tb.Marker(each='M', at=[{'days': 30}])

Set marks on the last Monday in May and the first Monday in September of each year:

>>> tb.Marker(each='A', 
...           at=[{'month': 5, 'week': -1, 'weekday': 1},
...               {'month': 9, 'week': 1, 'weekday': 1}],
...           how='nth_weekday_of_month')

See more examples and explanations in Making a Timeboard section of the documentation.

Attributes:	Same as parameters.

RememberingPattern class¶

class timeboard.RememberingPattern(labels)¶

Pattern keeping track of assigned labels across invocations.

An instance of this class is an iterator.

Parameters:	labels : iterable An iterable of workshift labels

Examples

Weeks are organized in a cycle of shifts ‘A’, ‘B’, ‘C’, ‘D’ with weekends being days off. The cycle of shifts resumes on Mondays keeping the track of uninterrupted shifts’ order:

>>> shifts_order = tb.RememberingPattern(['A', 'B', 'C', 'D'])
>>> week = tb.Marker(each='W', at=[{'days':0}, {'days':4}])
>>> shifts = tb.Organizer(marker=week, structure=[shifts_order, [-1]])

See more examples and explanations in Making a Timeboard section of the documentation.

Attributes:	length : int Number of elements in labels

Organizer class¶

Marker class¶

RememberingPattern class¶

Table of Contents

This Page