tessl/pypi-pandas
Powerful data structures for data analysis, time series, and statistics
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
time-series.mddocs/
Time Series and Date Handling
Comprehensive time series functionality including date/time parsing, time zone handling, frequency conversion, resampling, and specialized time-based operations.
Core Imports
import pandas as pd
from pandas import date_range, to_datetime, Timestamp, TimedeltaCapabilities
Date and Time Creation
Functions to create and manipulate date/time objects and ranges.
def date_range(start=None, end=None, periods=None, freq=None, tz=None, normalize=False, name=None, inclusive='both', **kwargs):
"""
Return a fixed frequency DatetimeIndex.
Parameters:
- start: str or datetime-like, left bound for generating dates
- end: str or datetime-like, right bound for generating dates
- periods: int, number of periods to generate
- freq: str or DateOffset, frequency string ('D', 'B', 'H', 'T', 'S', 'MS', etc.)
- tz: str or tzinfo, time zone name for localized DatetimeIndex
- normalize: bool, normalize start/end dates to midnight
- name: str, name of the resulting DatetimeIndex
- inclusive: str, whether to include both endpoints ('both', 'neither', 'left', 'right')
Returns:
DatetimeIndex
"""
def bdate_range(start=None, end=None, periods=None, freq='B', tz=None, normalize=True, name=None, weekmask=None, holidays=None, inclusive='both', **kwargs):
"""
Return a fixed frequency DatetimeIndex with business day default.
Parameters:
- start: str or datetime-like, left bound for generating dates
- end: str or datetime-like, right bound for generating dates
- periods: int, number of periods to generate
- freq: str or DateOffset, frequency string (default 'B' for business day)
- weekmask: str or None, weekmask of valid business days
- holidays: list-like or None, dates to exclude from valid business days
Returns:
DatetimeIndex
"""
def period_range(start=None, end=None, periods=None, freq=None, name=None):
"""
Return a fixed frequency PeriodIndex.
Parameters:
- start: str or Period, left bound for generating periods
- end: str or Period, right bound for generating periods
- periods: int, number of periods to generate
- freq: str or DateOffset, frequency string
- name: str, name of the resulting PeriodIndex
Returns:
PeriodIndex
"""
def timedelta_range(start=None, end=None, periods=None, freq=None, name=None, closed=None):
"""
Return a fixed frequency TimedeltaIndex.
Parameters:
- start: str or timedelta, left bound for generating timedeltas
- end: str or timedelta, right bound for generating timedeltas
- periods: int, number of periods to generate
- freq: str or DateOffset, frequency string
- name: str, name of the resulting TimedeltaIndex
- closed: str, make interval closed on 'left', 'right' or 'both' sides
Returns:
TimedeltaIndex
"""
def interval_range(start=0, end=None, periods=None, freq=None, name=None, closed='right'):
"""
Return a fixed frequency IntervalIndex.
Parameters:
- start: numeric or datetime-like, left bound for generating intervals
- end: numeric or datetime-like, right bound for generating intervals
- periods: int, number of periods to generate
- freq: numeric, datetime-like, or offset string, length of each interval
- name: str, name of the resulting IntervalIndex
- closed: str, whether intervals are closed on left, right, both, or neither
Returns:
IntervalIndex
"""Date and Time Conversion
Functions to parse and convert various date/time formats.
def to_datetime(arg, errors='raise', dayfirst=False, yearfirst=False, utc=None, format=None, exact=True, unit=None, infer_datetime_format=False, origin='unix', cache=True):
"""
Convert argument to datetime.
Parameters:
- arg: int, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like
- errors: str, error handling behavior ('raise', 'coerce', 'ignore')
- dayfirst: bool, interpret first value as day (DD/MM vs MM/DD)
- yearfirst: bool, interpret first value as year
- utc: bool, return UTC DatetimeIndex if True
- format: str, strftime format to parse time
- exact: bool, control how format is used
- unit: str, unit of numeric arg ('D', 's', 'ms', 'us', 'ns')
- infer_datetime_format: bool, attempt to infer format automatically
- origin: scalar, define reference date ('unix', '1900-01-01')
- cache: bool, use cache of unique, converted dates
Returns:
datetime, Timestamp, DatetimeIndex
"""
def to_timedelta(arg, unit=None, errors='raise'):
"""
Convert argument to timedelta.
Parameters:
- arg: str, timedelta, list-like, or Series
- unit: str, unit of arg when arg is numeric ('D', 'h', 'm', 's', 'ms', 'us', 'ns')
- errors: str, error handling behavior ('raise', 'coerce', 'ignore')
Returns:
timedelta, TimedeltaIndex, Series
"""
def infer_freq(index, warn=True):
"""
Infer most likely frequency given input index.
Parameters:
- index: DatetimeIndex or TimedeltaIndex
- warn: bool, warn if frequency cannot be inferred
Returns:
str or None, inferred frequency
"""Core Time Objects
Core pandas time-based scalar types for representing dates, times, and intervals.
class Timestamp:
def __init__(self, ts_input=None, freq=None, tz=None, unit=None, year=None, month=None, day=None, hour=None, minute=None, second=None, microsecond=None, nanosecond=None, tzinfo=None, fold=None):
"""
Pandas replacement for datetime.datetime.
Parameters:
- ts_input: datetime-like, str, int, float
- freq: str or DateOffset, offset which Timestamp will have
- tz: str, pytz.timezone, dateutil.tz.tzfile or None
- unit: str, unit of ts_input if ts_input is int or float
- year, month, day, hour, minute, second, microsecond, nanosecond: int
"""
def normalize(self):
"""Return timestamp truncated to midnight."""
def tz_localize(self, tz, ambiguous='raise', nonexistent='raise'):
"""Localize timestamp to given timezone."""
def tz_convert(self, tz):
"""Convert timestamp to given timezone."""
def strftime(self, format):
"""Format timestamp using strftime."""
def isoformat(self, sep='T', timespec='auto'):
"""Return ISO 8601 formatted string."""
def timestamp(self):
"""Return POSIX timestamp."""
class Timedelta:
def __init__(self, value=None, unit=None, **kwargs):
"""
Represents a duration between two dates or times.
Parameters:
- value: Timedelta, timedelta, np.timedelta64, str, or int
- unit: str, unit for value if value is numeric
"""
def total_seconds(self):
"""Total seconds in the timedelta."""
def to_pytimedelta(self):
"""Convert to python datetime.timedelta."""
def to_timedelta64(self):
"""Convert to numpy.timedelta64."""
class Period:
def __init__(self, value=None, freq=None, ordinal=None, year=None, month=None, day=None, hour=None, minute=None, second=None):
"""
Represents a period of time.
Parameters:
- value: Period, str, datetime, int
- freq: str or DateOffset
- ordinal: int, period ordinal value
"""
def asfreq(self, freq, how='E'):
"""Convert Period to desired frequency."""
def to_timestamp(self, freq=None, how='start'):
"""Return Timestamp representation of Period."""
def strftime(self, format):
"""Format Period using strftime."""
class Interval:
def __init__(self, left, right, closed='right'):
"""
An interval of values.
Parameters:
- left: orderable scalar, left bound of interval
- right: orderable scalar, right bound of interval
- closed: str, whether interval is closed ('left', 'right', 'both', 'neither')
"""
def overlaps(self, other):
"""Check whether two intervals overlap."""
def contains(self, other):
"""Check whether interval contains other."""
@property
def length(self):
"""Return length of interval."""
@property
def mid(self):
"""Return midpoint of interval."""
class DateOffset:
def __init__(self, n=1, normalize=False):
"""
Standard kind of date increment used for a date range.
Parameters:
- n: int, number of time periods
- normalize: bool, normalize start/end dates to midnight
"""
def apply(self, other):
"""Apply offset to datetime."""
def rollforward(self, dt):
"""Roll date forward to next offset."""
def rollback(self, dt):
"""Roll date backward to previous offset."""Time Zone Handling
Functions and methods for working with time zones.
# These are methods of DatetimeIndex and Timestamp:
# .tz_localize(tz, ambiguous='raise', nonexistent='raise') - attach timezone to naive datetime
# .tz_convert(tz) - convert timezone-aware datetime to another timezone
# Common timezone operations
def show_timezones():
"""Show list of available time zones."""
# Time zone constants and utilities (accessed via pandas)
import pandas as pd
# pd.Timestamp.now() - current timestamp
# pd.Timestamp.utcnow() - current UTC timestamp
# pd.Timestamp.today() - current local timestamp
# Timezone-aware operations
# pd.date_range(..., tz='UTC') - create timezone-aware DatetimeIndex
# pd.to_datetime(..., utc=True) - parse as UTCResampling and Frequency Conversion
Methods for changing the frequency of time series data.
# These are methods of DataFrame/Series with DatetimeIndex:
# .resample(rule, axis=0, closed=None, label=None, convention='start', kind=None, loffset=None, base=None, on=None, level=None, origin='start_day', offset=None, group_keys=False)
# Returns Resampler object with aggregation methods:
class Resampler:
"""GroupBy-like object for resampling operations."""
def mean(self, numeric_only=False):
"""Compute mean of groups."""
def sum(self, numeric_only=False, min_count=0):
"""Compute sum of groups."""
def min(self, numeric_only=False):
"""Compute min of groups."""
def max(self, numeric_only=False):
"""Compute max of groups."""
def count(self):
"""Compute count of groups."""
def std(self, ddof=1, numeric_only=False):
"""Compute standard deviation of groups."""
def var(self, ddof=1, numeric_only=False):
"""Compute variance of groups."""
def first(self, numeric_only=False, min_count=0):
"""Compute first value of groups."""
def last(self, numeric_only=False, min_count=0):
"""Compute last value of groups."""
def median(self, numeric_only=False):
"""Compute median of groups."""
def ohlc(self):
"""Compute open, high, low, close values."""
def apply(self, func, *args, **kwargs):
"""Apply function to each group."""
def aggregate(self, func=None, *args, **kwargs):
"""Aggregate using one or more operations."""
def transform(self, arg, *args, **kwargs):
"""Transform using one or more operations."""
def interpolate(self, method='linear', axis=0, limit=None, inplace=False, limit_direction=None, limit_area=None, downcast=None, **kwargs):
"""Interpolate values according to different methods."""
def asfreq(self, fill_value=None):
"""Convert to specified frequency."""
def fillna(self, value=None, method=None, axis=None, inplace=False, limit=None, downcast=None):
"""Fill missing values in resampled data."""
# Frequency conversion without aggregation
# .asfreq(freq, method=None, how=None, normalize=False, fill_value=None)Date Offsets and Business Calendar
Specialized offset classes for date arithmetic and business calendar operations.
# Import from pandas.tseries.offsets
from pandas.tseries.offsets import (
Day, Hour, Minute, Second, Milli, Micro, Nano,
BusinessDay, BDay,
CustomBusinessDay, CDay,
BusinessHour, CustomBusinessHour,
MonthEnd, BMonthEnd, MonthBegin, BMonthBegin,
SemiMonthEnd, SemiMonthBegin,
QuarterEnd, BQuarterEnd, QuarterBegin, BQuarterBegin,
YearEnd, BYearEnd, YearBegin, BYearBegin,
Week, WeekOfMonth, LastWeekOfMonth,
FY5253, FY5253Quarter,
Easter
)
# Business day offset with custom calendar
class CustomBusinessDay(DateOffset):
def __init__(self, n=1, normalize=False, weekmask='Mon Tue Wed Thu Fri', holidays=None, calendar=None, offset=timedelta(0)):
"""
Custom business day offset.
Parameters:
- n: int, number of periods
- weekmask: str or None, weekmask of valid business days
- holidays: list-like, dates to exclude from valid business days
- calendar: AbstractHolidayCalendar, holiday calendar to use
- offset: timedelta, time offset to apply
"""
# Holiday calendar support
class AbstractHolidayCalendar:
"""Abstract base class for holiday calendars."""
def holidays(self, start=None, end=None, return_name=False):
"""Return holidays between start and end dates."""
class USFederalHolidayCalendar(AbstractHolidayCalendar):
"""US Federal Holiday Calendar."""
pass
# Business hour offset
class BusinessHour(DateOffset):
def __init__(self, n=1, normalize=False, start='09:00', end='17:00', offset=timedelta(0)):
"""
Business hour offset.
Parameters:
- n: int, number of periods
- start: str, start time of business hours
- end: str, end time of business hours
- offset: timedelta, time offset to apply
"""Rolling Window Operations
Statistical operations over rolling windows of time series data.
# These are methods of DataFrame/Series:
# .rolling(window, min_periods=None, center=False, win_type=None, on=None, axis=0, closed=None, step=None, method='single')
# Returns Rolling object with statistical methods:
class Rolling:
"""Provides rolling window calculations."""
def count(self):
"""Count of non-null observations."""
def sum(self, numeric_only=False, engine=None, engine_kwargs=None):
"""Sum of values."""
def mean(self, numeric_only=False, engine=None, engine_kwargs=None):
"""Mean of values."""
def median(self, numeric_only=False, engine=None, engine_kwargs=None):
"""Median of values."""
def var(self, ddof=1, numeric_only=False, engine=None, engine_kwargs=None):
"""Variance of values."""
def std(self, ddof=1, numeric_only=False, engine=None, engine_kwargs=None):
"""Standard deviation of values."""
def min(self, numeric_only=False, engine=None, engine_kwargs=None):
"""Min of values."""
def max(self, numeric_only=False, engine=None, engine_kwargs=None):
"""Max of values."""
def corr(self, other=None, pairwise=None, ddof=1, numeric_only=False):
"""Correlation of values."""
def cov(self, other=None, pairwise=None, ddof=1, numeric_only=False):
"""Covariance of values."""
def skew(self, numeric_only=False):
"""Skewness of values."""
def kurt(self, numeric_only=False):
"""Kurtosis of values."""
def apply(self, func, raw=False, engine=None, engine_kwargs=None, args=None, kwargs=None):
"""Apply function to rolling window."""
def aggregate(self, func, *args, **kwargs):
"""Aggregate using one or more operations."""
def quantile(self, quantile, interpolation='linear', numeric_only=False):
"""Quantile of values."""
# Expanding window operations
# .expanding(min_periods=1, center=None, axis=0, method='single')
# Returns Expanding object with same methods as Rolling
class Expanding:
"""Provides expanding window calculations."""
# Same methods as Rolling class
pass
# Exponentially weighted operations
# .ewm(com=None, span=None, halflife=None, alpha=None, min_periods=0, adjust=True, ignore_na=False, axis=0, times=None, method='single')
# Returns ExponentialMovingWindow object
class ExponentialMovingWindow:
"""Provides exponentially weighted calculations."""
def mean(self, numeric_only=False, engine=None, engine_kwargs=None):
"""Exponentially weighted moving average."""
def var(self, bias=False, numeric_only=False, engine=None, engine_kwargs=None):
"""Exponentially weighted moving variance."""
def std(self, bias=False, numeric_only=False, engine=None, engine_kwargs=None):
"""Exponentially weighted moving standard deviation."""
def corr(self, other=None, pairwise=None, numeric_only=False):
"""Exponentially weighted moving correlation."""
def cov(self, other=None, pairwise=None, bias=False, numeric_only=False):
"""Exponentially weighted moving covariance."""Types
# Frequency strings
FrequencyStr = Literal[
'B', 'C', 'D', 'W', 'M', 'SM', 'BM', 'CBM', 'MS', 'SMS', 'BMS', 'CBMS',
'Q', 'BQ', 'QS', 'BQS', 'A', 'Y', 'BA', 'BY', 'AS', 'YS', 'BAS', 'BYS',
'BH', 'H', 'T', 'min', 'S', 'L', 'ms', 'U', 'us', 'N', 'ns'
]
# Time zone types
TimeZone = Union[str, datetime.tzinfo, None]
# Resample rule types
ResampleRule = Union[str, DateOffset]
# Date parse error handling
DateParseError = Literal['raise', 'coerce', 'ignore']
# Timestamp origin types
TimestampOrigin = Union[Literal['unix'], Timestamp, str]
# Missing value sentinels for datetime
NaT: object # Not-a-Time, pandas equivalent of NaN for datetime
# Interval closed options
IntervalClosed = Literal['left', 'right', 'both', 'neither']Install with Tessl CLI
npx tessl i tessl/pypi-pandas