econirl.TrajectoryPanel

class econirl.TrajectoryPanel(trajectories, metadata=<factory>)

Bases: Panel

Enhanced panel with efficient tensor operations and DataFrame I/O.

TrajectoryPanel keeps the list-of-Trajectory interface from Panel but adds efficient stacked tensor operations, DataFrame conversion, bootstrap resampling, transition iteration, and sufficient statistics computation.

All existing Panel methods and properties are inherited unchanged.

Parameters:

• trajectories (list[Trajectory])

• metadata (dict[str, Any])

property all_states: Array

Concatenated states array of shape (N,).

property all_actions: Array

Concatenated actions array of shape (N,).

property all_next_states: Array

Concatenated next_states array of shape (N,).

property offsets: Array

Cumulative individual lengths of shape (I+1,).

offsets[i] is the start index of individual i in the concatenated tensors; offsets[-1] == num_observations.

classmethod from_dataframe(df, state, action, id, next_state=None)

Create a TrajectoryPanel from a pandas DataFrame.

Parameters:

• df (pd.DataFrame) – Panel data with at least state, action, and id columns.

• state (str) – Column name for state indices.

• action (str) – Column name for action indices.

• id (str) – Column name for individual identifiers.

• next_state (str or None) – Column name for next-state indices. If None, next states are inferred from sequential rows within each individual.

Return type:

TrajectoryPanel

classmethod from_panel(panel)

Wrap an existing Panel as a TrajectoryPanel.

Parameters:

panel (Panel) – Existing panel to wrap.

Return type:

TrajectoryPanel

sufficient_stats(n_states, n_actions)

Compute sufficient statistics for tabular estimators.

Parameters:

• n_states (int) – Total number of states in the MDP.

• n_actions (int) – Total number of actions in the MDP.

Returns:

Pre-computed state-action counts, transitions, empirical CCPs, and initial state distribution.

Return type:

SufficientStats

resample_individuals(n=None, seed=None)

Bootstrap resample of individuals (trajectories).

Parameters:

• n (int or None) – Number of individuals in the resampled panel. Defaults to the same number as the original panel.

• seed (int or None) – Random seed for reproducibility.

Returns:

New panel with resampled trajectories (sampled with replacement).

Return type:

TrajectoryPanel

iter_transitions(batch_size=512, seed=0)

Iterate over (state, action, next_state) mini-batches.

Shuffles all transitions and yields them in batches for SGD-style training loops.

Parameters:

• batch_size (int) – Number of transitions per batch.

• seed (int) – Random seed for shuffling.

Yields:

tuple[Array, Array, Array] – (states, actions, next_states) each of shape (B,) where B <= batch_size.

Return type:

Iterator[tuple[Array, Array, Array]]

to_dataframe()

Convert panel to a pandas DataFrame.

Returns:

DataFrame with columns id, period, state, action, next_state.

Return type:

pd.DataFrame

save_npz(path)

Save panel to a compressed .npz file.

Stores all trajectories as flat arrays with an offset index so individual trajectories can be reconstructed on load. Metadata and individual IDs are preserved via pickle-compatible arrays.

Parameters:

path (str) – File path (should end in .npz).

Return type:

None

classmethod load_npz(path)

Load a panel from a .npz file created by save_npz.

Parameters:

path (str) – Path to .npz file.

Return type:

TrajectoryPanel

__init__(trajectories, metadata=<factory>)

Parameters:

• trajectories (list[Trajectory])

• metadata (dict[str, Any])

Return type:

None

compute_choice_frequencies(num_states, num_actions)

Compute empirical choice frequencies by state.

This gives the empirical conditional choice probabilities (CCPs) that can be used for CCP-based estimation methods.

Parameters:

• num_states (int) – Total number of possible states

• num_actions (int) – Total number of possible actions

Returns:

Array of shape (num_states, num_actions) with empirical CCPs

Return type:

Array

compute_state_frequencies(num_states)

Compute empirical state visit frequencies.

Parameters:

num_states (int) – Total number of possible states

Returns:

Array of shape (num_states,) with visit frequencies

Return type:

Array

classmethod from_numpy(states, actions, next_states, individual_ids=None)

Create Panel from numpy arrays with individual grouping.

Parameters:

• states (ndarray) – Array of shape (N,) with state indices

• actions (ndarray) – Array of shape (N,) with action indices

• next_states (ndarray) – Array of shape (N,) with next state indices

• individual_ids (ndarray | None) – Array of shape (N,) with individual identifiers. If None, all observations treated as one individual.

Returns:

Panel object with trajectories grouped by individual

Return type:

TrajectoryPanel

get_all_actions()

Concatenate all actions into a single array.

Return type:

Array

get_all_next_states()

Concatenate all next_states into a single array.

Return type:

Array

get_all_states()

Concatenate all states into a single array.

Return type:

Array

property num_individuals: int

Number of individuals in the panel.

property num_observations: int

Total number of state-action observations across all individuals.

property num_periods_per_individual: list[int]

List of number of periods for each individual.

trajectories: list[Trajectory]