Dates

`gaspatchio_core.column.namespaces.dt_proxy.DtNamespaceProxy` ¶

A proxy for Polars datetime (dt) namespace operations, enabling type-hinting and IDE intellisense for ActuarialFrame datetime manipulations.

This proxy intercepts calls to datetime methods, retrieves the underlying Polars expression from its parent proxy (either a ColumnProxy or ExpressionProxy), applies the datetime operation, and then wraps the resulting Polars expression back into an ExpressionProxy.

`getattr(name)` ¶

Dynamically handle any other methods available on Polars' dt namespace.

This provides a fallback for dt methods not explicitly defined on this proxy. It attempts to call the method via _call_dt_method.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the dt method to access.	required

Returns:

Type	Description
`Callable[..., 'ExpressionProxy']`	A callable that, when invoked, will execute the corresponding
`Callable[..., 'ExpressionProxy']`	Polars dt method and return an ExpressionProxy.

Raises:

Type	Description
`AttributeError`	If the method does not exist on the Polars dt namespace (raised by _call_dt_method if the underlying Polars call fails).

`init(parent_proxy, parent_af)` ¶

Initialize the DtNamespaceProxy.

This constructor is typically not called directly by users. It's used internally when accessing the .dt attribute of an ActuarialFrame column or expression proxy (e.g., af["my_date_col"].dt).

Parameters:

Name	Type	Description	Default
`parent_proxy`	`'ParentProxyType'`	The parent proxy (ColumnProxy or ExpressionProxy) from which this dt namespace is accessed.	required
`parent_af`	`Optional['ActuarialFrame']`	The parent ActuarialFrame, if available, for context.	required

`day()` ¶

Extract the day number of the month (1-31) from a date/datetime expression.

This function isolates the day component from a date or datetime, returning it as an integer (e.g., 15 for the 15th of the month). It works for both individual dates and lists of dates.

When to use

Extracting the day of the month can be useful in actuarial contexts for: * Specific Date Checks: Identifying events occurring on particular days (e.g., end-of-month processing). * Intra-month Analysis: Analyzing patterns within a month, though less common than month or year analysis. * Data Validation: Ensuring dates fall within expected day ranges for specific calculations.

Examples¶

Scalar example::

import polars as pl
from gaspatchio_core import ActuarialFrame
af = ActuarialFrame({"d": pl.Series(["2023-06-05", "2023-06-15"]).str.to_date()})
print(af.select(af["d"].dt.day().alias("day")).collect())

shape: (2, 1)
┌─────┐
│ day │
│ --- │
│ i8  │
╞═════╡
│ 5   │
│ 15  │
└─────┘

Vector (list) example – loss-event days::

import datetime
import polars as pl
from gaspatchio_core import ActuarialFrame
data = {
    "policy_id": ["E005", "F006"],
    "loss_event_dates": [
        [datetime.date(2023, 6, 5), datetime.date(2023, 6, 15)],
        [datetime.date(2024, 2, 1), datetime.date(2024, 2, 29)],
    ],
}
af = ActuarialFrame(data).with_columns(
    pl.col("loss_event_dates").cast(pl.List(pl.Date))
)
days_expr = af["loss_event_dates"].dt.day()
print(af.select("policy_id", days_expr.alias("event_days")).collect())

shape: (2, 2)
┌───────────┬────────────┐
│ literal   ┆ event_days │
│ ---       ┆ ---        │
│ str       ┆ list[i8]   │
╞═══════════╪════════════╡
│ policy_id ┆ [5, 15]    │
│ policy_id ┆ [1, 29]    │
└───────────┴────────────┘

`month()` ¶

Extract the month number (1-12) from a date or datetime expression.

This function allows you to isolate the month component from a series of dates or datetimes. The result is an integer representing the month, where January is 1 and December is 12.

When to use

In actuarial modeling, extracting the month from dates is crucial for various analyses. For instance, you might use this to:

Analyze seasonality in claims (e.g., identifying if certain types of claims are more frequent in specific months).
Group policies by their issue month for cohort analysis or to study underwriting patterns.
Determine premium due dates or benefit payment schedules that occur on a monthly basis.
Calculate fractional year components for financial calculations.

Examples¶

Scalar example::

import polars as pl
from gaspatchio_core import ActuarialFrame
af = ActuarialFrame({"d": pl.Series(["2022-01-01", "2022-02-01", "2022-03-01"]).str.to_date("%Y-%m-%d")})
print(af.select(af["d"].dt.month().alias("m")).collect())

shape: (3, 1)
┌─────┐
│ m   │
│ --- │
│ i8  │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Vector (list) example – claim-lodgement months::

import datetime
import polars as pl
from gaspatchio_core import ActuarialFrame
data = {
    "policy_id": ["C003", "D004"],
    "claim_lodgement_dates": [
        [datetime.date(2022, 3, 10), datetime.date(2022, 4, 5)],
        [datetime.date(2023, 1, 20), datetime.date(2023, 11, 30)],
    ],
}
af = ActuarialFrame(data).with_columns(
    pl.col("claim_lodgement_dates").cast(pl.List(pl.Date))
)
months_expr = af["claim_lodgement_dates"].dt.month()
print(af.select(pl.col("policy_id"), months_expr.alias("lodgement_months")).collect())

shape: (2, 2)
┌───────────┬──────────────────┐
│ policy_id ┆ lodgement_months │
│ ---       ┆ ---              │
│ str       ┆ list[i8]         │
╞═══════════╪══════════════════╡
│ C003      ┆ [3, 4]           │
│ D004      ┆ [1, 11]          │
└───────────┴──────────────────┘

`year()` ¶

Extract the year from the underlying datetime expression.

This function isolates the year component from a date or datetime, returning it as an integer (e.g., 2023). It is applicable to both single date values and lists of dates within your ActuarialFrame.

When to use

Extracting the year is fundamental in actuarial analysis for: * Valuation and Reporting: Determining the calendar year for financial reporting or regulatory submissions. * Experience Studies: Grouping data by calendar year of event (e.g., year of claim, year of lapse) to analyze trends. * Cohort Analysis: Defining cohorts based on the year of policy issue or birth year. * Projection Models: Calculating durations or projecting cash flows based on calendar years.

Examples¶

Scalar example (single-date column)::

import polars as pl
from gaspatchio_core import ActuarialFrame
data = {
    "dates": pl.Series(["2020-01-15", "2021-07-20"]).str.to_date(format="%Y-%m-%d")
}
af = ActuarialFrame(data)
year_expr = af["dates"].dt.year()
print(af.select(year_expr.alias("year")).collect())

shape: (2, 1)
┌──────┐
│ year │
│ ---  │
│ i32  │
╞══════╡
│ 2020 │
│ 2021 │
└──────┘

Vector example (list-of-dates per policy)::

import datetime
import polars as pl
from gaspatchio_core import ActuarialFrame
data_vec = {
    "policy_id": ["A001", "B002"],
    "policy_event_dates": [
        [datetime.date(2019, 12, 1), datetime.date(2020, 1, 20)],
        [datetime.date(2021, 5, 10), datetime.date(2021, 8, 15), datetime.date(2022, 2, 25)],
    ],
}
af_vec = ActuarialFrame(data_vec)
af_vec = af_vec.with_columns(pl.col("policy_event_dates").cast(pl.List(pl.Date)))
years_expr = af_vec["policy_event_dates"].dt.year()
print(af_vec.select(pl.col("policy_id"), years_expr.alias("event_years")).collect())

shape: (2, 2)
┌───────────┬────────────────────┐
│ policy_id ┆ event_years        │
│ ---       ┆ ---                │
│ str       ┆ list[i32]          │
╞═══════════╪════════════════════╡
│ A001      ┆ [2019, 2020]       │
│ B002      ┆ [2021, 2021, 2022] │
└───────────┴────────────────────┘

Dates

gaspatchio_core.column.namespaces.dt_proxy.DtNamespaceProxy ¶

__getattr__(name) ¶

__init__(parent_proxy, parent_af) ¶

day() ¶

Examples¶

month() ¶

Examples¶

year() ¶

Examples¶

`gaspatchio_core.column.namespaces.dt_proxy.DtNamespaceProxy` ¶

`getattr(name)` ¶

`init(parent_proxy, parent_af)` ¶

`day()` ¶

`month()` ¶

`year()` ¶