Employee Leave Period Optimiser Heatmap

A script for South African employees seeking the longest vacation possible using the least amount of annual leave days.

(APPROVAL OF LEAVE NOT INCLUDED)

Table of Contents

• Introduction
• Technologies
• How to Use
  • Examples
  • Tips
• How it works
• Known Issues
• References

Introduction

Are you a tired South African employee looking to take a few days off but only have a few annual leave days? Then look no further! I developed a Python script which determines the best time to take leave in the year based on the total number of annual leave days you are willing to use.

Technologies

• Python
• SQL
• Jupyter

Setup

• Install all relevant Python packages
• Create your own API key by creating a free account with Calendarific
• Paste API key by 'key' variable situated in 'holiday_data_from_api' function

def holiday_data_from_api(current_year):
	key = 'insert your own API key here'

• Choose the number of leave days you would like to use
• The year is automatically set to the current year but can be changed if needed

#input parameters
current_year = int(datetime.datetime.now().date().strftime("%Y"))
no_of_leave_days = "How many leave days are you willing to use?"

How to Use

If you don't want to use the script, there is an infographic for the current year using 0 - 3 annual days in the output folder.

• Colour bar (far right): total number of days off range
• Blocks in calendar heatmap:
  • Number - date
  • Colour - the total number of leaves days you receive if you start your leave on that block (Refer to colour bar)

Examples

For employees willing to use 3 annual days:

• If you start your leave from the 16th June 2022:

  • you get 6 days off.
  • Leave will start on the 16th June 2022
  • return to work on the 22nd June 2022.

• If you start your leave from the 21st March 2022:

  • you get 4 days off. 
  • Leave will start on the 16th June 2022
  • return to work on the 25th March 2022.

Tips

• Start with 'no_of_leave_days' = 0 to see how many days off you can get without using any leave.

How it Works

The scripts assumes the South African employee works five days a week and takes the the weekends (Saturday and Sunday) off. Additionally, the assumption is that the company gives leave based on South African public holidays.

For each day, the script checks the starting leave day and the following days whether it is a working day/public holiday/weekend. If it is a working day, the chosen annual leave days are deducted by one until there are no days left.

If the day is a public holiday/weekend, the total days off is increased by one (Refer to function: 'total_days_off_sql'). This can be summarised in the equation shown below:

Total Days Off = no. of Weekends + no. of Public Holidays + total no. of Annual leave days

A summary of the script can be seen in the image below.

Known Issues

• July's Heatmap's days off colour bar can be confusion at times as it sometimes show float data types (e.g. 1.2, 1.4, 5.6, etc) when days should be integers. Additionally, the numbers at times are slightly offset from its designate colour.
• Keep number of leave days relatively small (< 10 days) for reasonable values

References

• July Documentation
• Calendarific
• Create date range with Pandas
• Python Check if Date is Weekend or Weekday
• Continuous Color Scales and Color Bars in Python
• Public holidays in South Africa

(Return to Table of Contents)

---