fiscal445

Description

This script was developed to simplify the determination of reporting dates when using a 445 financial calendar. Many companies use the 445 calendar for financial reporting and it is difficult when setting up reports for YTD, MTD, by quarter runs while only relying on a standard calendar. This module simplifies this by allowing you to set your own start of the year date and weekending day.

Prerequisites

Built and tested using

python 3.6+, pandas 0.25.3+, numpy 1.18.0, datetime, sys,

Deployment

General Deployment

python -m pip install fiscal445

Usage

Import the module

import fiscal445 as fc5

Set the modules parameters.

To initialize the 445 calendar table

Syntax: fc5.cal = fc5.Calendar('YYYY-MM-DD','day').build() where the date is the start of your fiscal 445 year and the day arg is the the last day of your fiscal week.

Examples:

fc5.cal = fc5.Calendar('2020-02-02','sat').build()

Optional: capturing calendar-boundary days (capture_outliers)

Some companies publish their 445 calendar so that it doesn't quite cover every day of the calendar year — typically 1-6 days at the very start or end of the year fall outside any fiscal week entirely. That's fine as long as your underlying sales/transaction data respects the same boundary. In practice it often doesn't: the source data covers every calendar day (365/366), but the reporting structure is strictly 445, so those few boundary days become orphaned — present in the data, but outside any week the calendar recognizes, and easy to miss unless someone remembers to pull them separately by hand.

capture_outliers fixes this by folding those boundary days into week 1 (at the start of the year) and week 52 (at the end), so the calendar covers every calendar day of the year with no gaps — while leaving every other week-ending date completely unchanged.

Syntax: fc5.cal = fc5.Calendar('YYYY-MM-DD','day',capture_outliers=True).build()

It defaults to False, so any existing code that doesn't pass this argument behaves exactly as it always has.

Example

# 2016's fiscal year begins Saturday, Jan 2 -- meaning Friday, Jan 1
# would otherwise be excluded from every week.
fc5.cal = fc5.Calendar('2016-01-02', 'fri', capture_outliers=True).build()

Without capture_outliers, any query built on this calendar — a week range, a quarter range, year to date — can never reach Jan 1, 2016; that date simply doesn't exist anywhere in the table. With it enabled, week 1 now correctly spans Jan 1 through Jan 8. The same logic applies symmetrically at the other end of the year, if the last week falls short of Dec 31.

fc5.cal.show.quarter_dates(1)

Without capture_outliers: ('2016-01-02', '2016-04-01')
With capture_outliers: ('2016-01-01', '2016-04-01')

Week of the month it is based on 445 fiscal calendar

fc5.cal.show.cur_week_of_month()

returns 1 based on example date

fc5.cal.show.prior_week_of_month()

returns 5 based on example date

Week of the year it is based on 445

fc5.cal.show.cur_week_of_year()

returns 5

Which month of the year it is based on 445 calendar

fc5.cal.show.cur_month({optional arg})

returns 'March' without optional arg

With optional arg example: fc5.cal.show.cur_month(3) Returns a sliced string, where the length is based on the optional int arg, representing the name of the month ('Mar') of the year it is, based on the 445 calendar'''

Which month of the year it is based on 445 calendar minus one week

fc5.cal.show.month_of_prior_week({optional arg})

returns 'March' without optional arg

With optional arg example: fc5.cal.show.month_of_prior_week(3) Returns a sliced string, where the length is based on the optional int arg, representing the name of the month ('Mar') of the year it is, based on the 445 calendar minus one week'''

Start and end for month to date

fc5.cal.show.month_to_date()

Returns a tuple of the start and end date for month to date reports

('2020-03-01', '2020-03-09')

Start and end for month to date most recent week completed

fc5.cal.show.month_to_date_completed()

returns a tuple of the start and end date for month to date reports for up to the most completed week

('2020-03-01', '2020-03-08')

returns the following if there has not been an entire complete fiscal week for that month.

'Not available yet!'

Start and end for year to date

fc5.cal.show.year_to_date()

returns a tuple

('2020-02-02', '2020-03-07')

Start and end for year to date most recent week completed

fc5.cal.show.year_to_date_completed

returns a tuple

('2020-02-02', '2020-02-29')

Start and end dates for completed quarters.

1 for Q1, 2 for Q2, 3 for Q3, 4 for Q4

arg is int value for quarter indicated above. fc5.cal.show.quarter_dates(arg)

fc5.cal.show.quarter_dates(1)

returns a tuple

('2020-02-02', '2020-05-02')

Start and end for quarter to date.

1 for Q1, 2 for Q2, 3 for Q3, 4 for Q4

arg is int value for quarter above. fc5.cal.show.quarter_to_date(arg)

fc5.cal.show.quarter_to_date(1)

returns a tuple

('2020-02-02', '2020-03-07')

returns the following if the current date is before the requested quarter

'Quarter not available!'

To view the entire calendar after you have initialized it.

print(fc5.cal)

Authors

Dv8edRoute - Original code

License

MIT

Acknowledgments