psuedomagi / fedcal

A feature-rich Python calendar that enables time series analyses of changes in federal workforce schedules and shifts in executive department funding status.

fedcal, a democratic python calendar enhancement to pandas

Current version - unstable alpha 0.1

Current Status

In active early-stage development. 16 Jan 2024 - Completely overhauled/refactored back-end, now it's time for the front end. I'm branching off that development from dev until further along. Offsets module and its helpers are functional but mostly untested, but I wanted to make it available while I overhaul the rest of the front-end. With the exception of FedHolidays, offsets are fully vectorized for snappy scalar and array operations (which isn't entirely true for pandas native offsets, at some point I may try to rewrite pd.AbstractHolidayCalendar to be more vectorized... maybe even pull it into Cython). On the branch, I'm working to fully integrate fedcal functionality into Pandas' extensions API (and maybe some more direct reverse engineering hacks--if necessary--like I did with the offsets module), providing fedcal accessors to Index, Series, and DataFrame for seamless integration, and once tested, joining the pydata extensions community. This will be functionally similar to the 'dt' accessor for datetime Series, (e.g. my_series.fc.fy will yield the Federal fiscal year for the date(s)). I'm not yet sure how I'm going to build in front-end executive department appropriations status data, possibly with a custom pandas ExtensionArray and supporting dtype for rich functionality. In digging through Pandas source to get the library where it is, I learned a lot about how pandas ticks, so I'm hoping to put that knowledge to work for fedcal.

Available/Functional but untested: offsets.py - custom pandas DateOffsets for civilian and military paydays (FedPayDay, MilitaryPayDay), Federal holidays including past proclamation holidays (FedHolidays), federal business days accounting for federal holidays (FedBusinessDay), and a class to identify likely military passdays falling on business days and adjacent to federal holidays (MilitaryPassDay). _status_factory.py fetch_index - this is really part of the backend, but for anyone who wants accessible time series appropriations data by executive department, you can currently pull a multiindex using the fetch_index function. You can also roll your own by pulling the status_intervals.json where the data are stored.

fedcal

fedcal is a simple calendar library with one big goal: enable new perspective on the U.S. Government to build transparency, improve government, and bolster democracy.

a calendar... why?

The U.S. Government is massive. Over two million civilian and military employees. 1.7 trillion dollars in FY23 spending. Even tiny and short-lived changes and shifts in the government workforce and spending can have far-reaching impacts over time.

Time is at the heart of those impacts. I'm a federal manager, and I started writing fedcal because I wanted to understand how shifts in personnel availability, seasonality, and budgetary factors impacted productivity to help me plan and drive better results. For example, I know first hand how devastating the continuing resolution cycle can be on productivity and outcomes, but didn't know precisely how devastating those impacts could be (or how subtle and unexpected). I was shocked to find there weren't off-the-shelf solutions for understanding the basic rhythms and routines of the massive U.S. Government machine

fedcal is about answering big and small questions, improving predictions, and understanding the U.S. Government, its effect on society and the world

Note

If you think about it, the U.S. Government is a big control group, of sorts. Two million people are mostly at work... or they aren't because of holidays, weekends, military passdays, or government shutdowns. One minute the government is 'on', and the next it is 'off'. Of course, it's more complicated than that -- sometimes only half, a third, or 90% of the government is impacted, which offers opportunities for even richer differential analysis (and one fedcal hopes to enable). But it's not just shutdowns -- a continuing resolution instead of a full year appropriation is another kind of binary relationship, or even whether a holiday falls on a Monday or Tuesday. fedcal aims to give you the tools to explore these relationships and their significance (...or insignificance).

A few example questions fedcal can help answer:

productivity analysis

• What impacts do continuing resolutions (CRs), full-year appropriations, and, of course, shutdowns, have on Federal services? How long do those impacts linger, and how quickly, when, and how are they propagated?
• Which departments feel these impacts the most?
• How do holidays and military passdays affect seasonal outcomes and workforce productivity? How long do those effects extend?
• How do those same factors impact Federal contractor productivity? ... private business? ...agriculture? ...industrial security?

economic/financial analysis

• How do changes in federal appropriations (i.e. full-year appropriations, continuing resolutions, gaps/shutdowns) affect not just the U.S. economy, but state, local, international economies? Federal contractors and employees? Businesses reliant on federal employees?
• How fast do those impacts propagate? How quickly do they heal?
• How do federal paydays and holidays impact small businesses and local economies (e.g. for a military town, or a deli across the street from a federal building)?

business and human resources analysis

• How do changes in U.S. Government budgeting and productivity impact contracting and demand? Are they accurately predictable? How long does it take those shifts to propagate into financial outcomes for businesses dependent on the Government.
• How do shifts in government budgeting or personnel affect supply and demand for human capital? Federal hiring? Talent availability?

social science

• Are Congress' irregularities more routine and predictable than they might appear? Are certain committees more consistently effective at passing appropriations? Why?
• What are the social, political, and economic costs of irregular Federal budgeting?
• What unexpected correlations are there for leave or short interruptions in personnel from holidays, military passes, and similar factors (e.g. Some shots in the dark: are smokeless tobacco sales measurably impacted by military leave in military communities? Are certain crimes more or less likely when federal employees get Christmas Eve off? Do military passdays alter dependent educational outcomes in subsequent weeks)?
• Are federal employees more likely to make certain purchases or financial decisions before or after paydays?

more routine stuff

Of course, as a calendar library, fedcal can help you streamline more development for routine needs like:

• leave and pay automation systems
• financial systems (i.e. bank holidays, deposit prediction (hello USAA!))
• informational websites
• whatever else you can think up

okay, I'm sold, but what does it do?

The fedcal API bolts on Federal data/time information enhancements to two of the most powerful classes in data science for time series analysis - pandas' Timestamp and DatetimeIndex:

1. FedStamp - fedcal's enhanced sub-class to pandas' Timestamp class

2. FedIndex a companion class that adds similar functionality to pandas' DatetimeIndex class

Important

FedStamp and FedIndex retain all functionality of pandas Timestamp and DatetimeIndex. (... or they should, pending testing and refinement and your issue submissions...)

Core Enhancements to Timestamp and DatetimeIndex

1. Department-level appropriations/operational status for all top-level Federal Departments over time, with shutdown and appropriations gap data from FY75 to present, and continuing resolutions data from FY99 to present (currently -- I plan to delve back to FY75 eventually)

2. Federal date attributes 1970 to whenever:

   • Federal Holidays, including historical holidays by Presidential proclamation (also back to FY75).
   • Federal businessdays (1970 to indefinite future - why 1970? I use POSIX time as a reasonable floor; no other reason.)
   • Federal fiscal years and fiscal quarters (1970 to whenever)
   • fedcal can even take a very rough guess of whether a future President will declare a given Christmas Eve a holiday

3. Federal civilian biweekly paydays

4. Military paydays and estimated holiday passdays

5. Supporting time utilities like to_timestamp and to_datetimeindex

6. Suggestions?

what's next?

• Lots of bug fixes before initial alpha
• error handling
• thorough test coverage
• CI/CD pipeline and packaging for pypi deployment
• fullsome documentation
• performance optimizations (e.g. vectorize date range lookups for department statuses)
• API enhancements (e.g. feature encoding) and removing artifacts of design changes
• adding CR data to FY75

how can I help?

Review the CODE_OF_CONDUCT.md and CONTRIBUTING.md to get started. Please help!