mmamaev/timeboard

Calendar calculations over business days and work shifts

timeboard - business calendar calculations

timeboard creates schedules of work periods and performs calendar calculations over them. You can build standard business day calendars as well as a variety of other schedules, simple or complex.

Examples of problems solved by timeboard:

• If we have 20 business days to complete the project when will be the deadline?
• If a person was employed from November 15 to December 22 and salary is paid monthly, how many month's salaries has the employee earned?
• The above-mentioned person was scheduled to work Mondays, Tuesdays, Saturdays, and Sundays on odd weeks, and Wednesdays, Thursdays, and Fridays on even weeks. The question is the same.
• A 24x7 call center operates in shifts of varying length starting at 02:00, 08:00, and 18:00. An operator comes in on every fourth shift and is paid per shift. How many shifts has the operator sat in a specific month?
• With employees entering and leaving a company throughout a year, what was the average annual headcount?

Based on pandas timeseries library, timeboard gives more flexibility than pandas's built-in business calendars. The key features of timeboard are:

• You can choose any time frequencies (days, hours, multiple-hour shifts, etc.) as work periods.
• You can create sophisticated schedules which can combine periodical patterns, seasonal variations, stop-and-resume behavior, etc.
• There are built-in standard business day calendars (in this version: for USA, UK, and Russia).

Installation

pip install timeboard

timeboard is tested with Python versions 2.7, 3.6 - 3.10.

Dependencies:

• pandas >= 0.22
• numpy >= 1.13
• dateutil >= 2.6.1
• six >= 1.11

The import statement to run all the examples:

>>> import timeboard as tb

Quick Start Guide

Set up a timeboard

To get started you need to build a timeboard (calendar). The simplest way to do so is to use a preconfigured calendar which is shipped with the package. Let's take a regular business day calendar for the United States.

>>> import timeboard.calendars.US as US
>>> clnd = US.Weekly8x5()

Note

If you need to build a custom calendar, for example, a schedule of shifts for a 24x7 call center, Making a Timeboard section of the documentation explains this topic in details.

Once you have got a timeboard, you may perform queries and calculations over it.

Play with workshifts

Calling a timeboard instance clnd with a single point in time produces an object representing a unit of the calendar (in this case, a day) that contains this point in time. Object of this type is called workshift.

Is a certain date a business day?

>>> ws = clnd('27 May 2017')
>>> ws.is_on_duty()
False

Indeed, it was a Saturday.

When was the next business day?

>>> ws.rollforward()
Workshift(6359) of 'D' at 2017-05-30

The returned calendar unit (workshift) has the sequence number of 6359 and represents the day of 30 May 2017, which, by the way, was the Tuesday after the Memorial Day holiday.

If we were to finish the project in 22 business days starting on 01 May 2017, when would be our deadline?

>>> clnd('01 May 2017') + 22
Workshift(6361) of 'D' at 2017-06-01

This is the same as:

>>> clnd('01 May 2017').rollforward(22)
Workshift(6361) of 'D' at 2017-06-01

Play with intervals

Calling clnd() with a different set of parameters produces an object representing an interval on the calendar. The interval below contains all workshifts of the months of May 2017.

How many business days were there in a certain month?

>>> may2017 = clnd('May 2017', period='M')
>>> may2017.count()
22

How many days off?

>>> may2017.count(duty='off')
9

How many working hours?

>>> may2017.worktime()
176.0

An employee was on the staff from April 3, 2017 to May 15, 2017. What portion of April's salary did the company owe them?

Calling clnd() with a tuple of two points in time produces an interval containing all workshifts between these points, inclusively.

>>> time_in_company = clnd(('03 Apr 2017','15 May 2017'))
>>> time_in_company.what_portion_of(clnd('Apr 2017', period='M'))
1.0

Indeed, the 1st and the 2nd of April in 2017 fell on the weekend, therefore, having started on the 3rd, the employee checked out all the working days in the month.

And what portion of May's?

>>> time_in_company.what_portion_of(may2017)
0.5

How many days had the employee worked in May?

The multiplication operator returns the intersection of two intervals.

>>> (time_in_company * may2017).count()
11

How many hours?

>>> (time_in_company * may2017).worktime()
88

An employee was on the staff from 01 Jan 2016 to 15 Jul 2017. How many years this person had worked for the company?

>>> clnd(('01 Jan 2016', '15 Jul 2017')).count_periods('A')
1.5421686746987953

Links

Documentation: https://timeboard.readthedocs.io/

GitHub: https://github.com/mmamaev/timeboard

PyPI: https://pypi.python.org/pypi/timeboard

License

BSD 3 Clause

timeboard's Issues

minutes is not working in timeboard.marker

`tb.Marker(each='D',at=[{'hours':7,'minutes':15, 'seconds':0}, {'hours':15, 'minutes':45, 'seconds':0}], how='from_start_of_each')
shifts = tb.Organizer(marker=day_parts, structure=[3,1,2])
clnd = tb.Timeboard(base_unit_freq='H',start='01 Apr 2019 00:15', end='01 Apr 2020 00:15', layout=shifts)

`
minutes nor seconds don't even show up in the daily marker, why? is this not a feature? wasted a lot of time over this

How to make schedule for Teachers within a day

I want to make a schedule for periods over which teachers ( let's say 9 subjects are taught)teach and I want to automatically schedule a timeboard showing schedules that don't clash.A period has 45 minutes. I also want to insert conditions such as the time a particular teacher is available.

Hourly schedule for a weeks or months [QA]

Hi @mmamaev , first of all thanks for such a great package!
Trying different settings for build, I think, very basic schedule. Need to display hourly schedule for a next few weeks for example and have a two different layouts, one for day hours and one for week days, so and can't mix it together.
p.s. asked here, because it can be a useful scenario.

Thanks

Working hours

Suppose I am making a calendar for a machine in my company and I want to give the working hours for that to a calender say from morning 6am to evening 6pm how can i do that?

Creating timeboard for current year months

Hi I am creating a time board for an application, while creating a calendar for Jan 2021, seems that the current year is still not supported?

jan2021 = clnd('Jan 2021', period='M') jan2021.count()
Interval referenced by Jan 2021 is completely outside Timeboard of 'D': 2000-01-01 -> 2020-12-31

Support for Python 3.8

Hi,

I tried to install your package with Python 3.8. I saw that it was not tested for support Python 3.8, but things even worse for me. I couldn't install it because of blocked dependency.

Here is your current requirements.txt:

pandas >=0.22,<=0.24; python_version < '3.6.1'
pandas >=0.22; python_version >= '3.6.1'
numpy >=1.13,<=1.16; python_version < '3.6'
numpy >=1.16; python_version >= '3.6'
python-dateutil>=2.6.1
six

On my system installed:

python --version
Python 3.6.9

But if i use pipdeptree to check for requirements i see:

pipdeptree -r -p pandas
pandas==0.24.0
  - timeboard==0.2.3 [requires: pandas>=0.22,<=0.24]

Where it should say pandas >=0.22 since I use Python 3.6.9.

I believe in your requirements.txt you have made a mistake. According to PEP 508 Environment Markers python_version resolves as 3.6 in my case. Where if you want full version info you should use python_full_version. Which will correctly resolve to 3.6.9 in my case.

Visualizing the time board

Hello, thank you for sharing this. This is great. Was wondering if there is a way to visualize a timeboard like how you do have in the article on free code camp. If so, could you please share how we would visualize the schedule/time board of one of the generic calenders?
Thank you

Saving timeboard to DB

Is there a way to save my timeboard to a DB such as PostgreSQL for future use?

Unable to create Timeboards

import timeboard.calendars.UK as UK
clnd = UK.Weekly8x5()

Produces error: TypeError: new() got an unexpected keyword argument start
There doesn't seem to be a way of creating timeboards, either through the calendar or directly

Finding out a portion of period

A user wants to obtain answers to questions like "What portion of year 2017 has an emplyee X been with the company". Since an employee may have entered or left the company at any time, both within and without, of year 2017, count_periods() do not fit the task.

The task calls for a calculation over the intersection of two intervals: one for the employee's tenure and the other for the period in question. It can be done manually but the task is quite common to be given a dedicated method.

ImportError: cannot import name 'Iterable' from 'collections'

In Python 3.10 its not working and shows the following error:

Traceback (most recent call last):
  File "xxx", line 2, in <module>
    import timeboard as tb
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/timeboard/__init__.py", line 7, in <module>
    from .timeboard import Timeboard
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/timeboard/timeboard.py", line 2, in <module>
    from .core import (_Frame, _Timeline, _Schedule,
  File "/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/site-packages/timeboard/core.py", line 11, in <module>
    from collections import Iterable, OrderedDict
ImportError: cannot import name 'Iterable' from 'collections' (/Library/Frameworks/Python.framework/Versions/3.10/lib/python3.10/collections/__init__.py)

Process finished with exit code 1

This seems to be simmilar to this issue:
noirbizarre/flask-restplus#766

Availability Check

Hi,

This package is awesome. Can it be used in a hotel booking application? To check availability of hotels, rooms etc? Did not see such an application in the example use cases.

Thanks in advance :)

User holiday (Annual Leave)

Hi,
I notice when generating calenders you can mark particular days as holidays. In this case all staff would be off.
Is there the functionality to mark a specific employee as holiday on a specific day?
Thanks.

Future warnings

I just upgraded to Python 3,6, and installed timeboard to go with this, and am now getting -

FutureWarning: Creating a PeriodIndex by passing range endpoints is deprecated. Use pandas.period_range instead.
timeboard/calendars/calendarbase.py:51:
timeboard/calendars/calendarbase.py:68:
timeboard/core.py:228:
timeboard/core.py:510:

and -
numpy/core/fromnumeric.py:56: FutureWarning: Series.nonzero() is deprecated and will be removed in a future version.Use Series.to_numpy().nonzero() instead

I'm not sure which component has changed to cause this, but I guess pandas. The latter one looks like a mismatch between pandas and numpy, but the first ones suggest changes required in timeboard?