Function `baltic.calendarDate`

calendarDate() Function

Description

The calendarDate() function in BALTIC converts decimal dates back to a specified calendar date format. This function is essentially the inverse of decimalDate().

Syntax

def calendarDate(timepoint, fmt='%Y-%m-%d')

Parameters

• timepoint (float): The decimal representation of the date.
• fmt (str): The desired format of the output date string. Default is '%Y-%m-%d'.

Return Value

• str: The date in the specified calendar format.

Functionality

1. Extracts the year from the decimal date.
2. Calculates the remaining fraction of the year.
3. Converts this fraction to a timedelta.
4. Adds the timedelta to the beginning of the year to get the exact date and time.
5. Formats the resulting datetime object according to the specified format.

Use Cases

1. Converting decimal dates back to calendar dates for human-readable output.
2. Preparing date labels for time axis in plots.
3. Reversing decimal date calculations for data presentation.
4. Generating date strings in specific formats from numerical time representations.

Example

import baltic as bt

# Basic usage
print(bt.calendarDate(2023.3923497267758))
# Output: '2023-05-24'

# Custom output format
print(bt.calendarDate(2023.5, fmt='%B %d, %Y'))
# Output: 'July 02, 2023'

# Year-only output
print(bt.calendarDate(2023.0, fmt='%Y'))
# Output: '2023'

# Precise timestamp output
print(bt.calendarDate(2023.75, fmt='%Y-%m-%d %H:%M:%S'))
# Output: '2023-10-01 00:00:00'

Notes

• The function handles leap years correctly, ensuring accurate date calculations.
• The precision of the output depends on the format string provided. For example, using '%Y' will only return the year, regardless of the decimal portion of the input.
• This function is particularly useful when you need to convert numerical time representations (often used in calculations or visualizations) back to human-readable dates.
• If you need to round the date to a specific precision (e.g., to the nearest day), you might need to apply rounding to the input timepoint before calling this function.
• The function assumes that the input timepoint is a valid decimal date (e.g., 2023.5 for midyear). Invalid inputs may produce unexpected results.