codeflash-agent/.tessl/tiles/tessl/pypi-pandas/docs/time-series.md

# 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

```python
import pandas as pd
from pandas import date_range, to_datetime, Timestamp, Timedelta
```

## Capabilities

### Date and Time Creation

Functions to create and manipulate date/time objects and ranges.

```python { .api }
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.

```python { .api }
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.

```python { .api }
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.

```python { .api }
# 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 UTC
```

### Resampling and Frequency Conversion

Methods for changing the frequency of time series data.

```python { .api }
# 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.

```python { .api }
# 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.

```python { .api }
# 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

```python { .api }
# 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']
```