Reader

This module implements functions to read or export trajectory data from external files.

from pycfrl import reader

pycfrl.reader.reader.convert_trajectory_to_dataframe(zs: list | ndarray, states: list | ndarray, actions: list | ndarray, rewards: list | ndarray, ids: list | ndarray, z_labels: list[str] | None = None, state_labels: list[str] | None = None, action_label: str | None = None, reward_label: str | None = None, id_label: str | None = None, T_label: str | None = None) → DataFrame

Convert trajectories from Trajectory Arrays into a pandas.DataFrame.

The output dataframe follows the format specified in the “Tabular Trajectory Data” document of the “Inputs and Outputs” section. The output dataframe will also contain a column that records the time steps of each row, where the time steps start from 1.

Args:

zs (list or np.ndarray):

The observed sensitive attributes of each individual in the trajectory. It should be a list or array following the Sensitive Attributes Format.

states (list or np.ndarray):

The state trajectory. It should be a list or array following the Full-trajectory States Format.

actions (list or np.ndarray):

The action trajectory. It should be a list or array following the Full-trajectory Actions Format.

rewards (list or np.ndarray):

The reward trajectory. It should be a list or array following the Full-trajectory Actions Format.

ids (list or np.ndarray):

The IDs of each individual in the trajectory. It is an array with size (N, 1) where N is the number of individuals in the trajectory. Specifically, ids[i, 0] contains the ID of the i-th individual in the trajectory.

z_labels (list[str], optional):

A list of strings representing the labels of columns in the output dataframe that should contain sensitive attribute variables. When set to None, the function will use default names z1, z2, … That is, the i-th component of the sensitive attribute vector will be named zi.

state_labels (list[str]):

A list of strings representing the labels of columns in the output dataframe that should contain state variables. When set to None, the function will use default names state1, state2, … That is, the i-th component of the state vector will be named statei.

action_label (str):

The label of the column in the output dataframe that should contain actions. When set to None, the column that contains actions will be named action by default.

reward_label (str):

The label of the column in the output dataframe that should contain rewards. When set to None, the column that contains rewards will be named reward by default.

id_label (str):

The label of the column in output dataframe that should contain IDs. When set to None, the column that contains IDs will be named ID by default.

T_label (str):

The label of the column in output dataframe that should contain time steps. When set to None, the column that contains time steps will be named timestamp by default.

Returns:

data (pandas.DataFrame):

A dataframe that contains the input trajectories in the format specified in the “Tabular Trajectory Data” document of the “Inputs and Outputs” section.

pycfrl.reader.reader.export_trajectory_to_csv(path: str, zs: list | ndarray, states: list | ndarray, actions: list | ndarray, rewards: list | ndarray, ids: list | ndarray, z_labels: list[str] | None = None, state_labels: list[str] | None = None, action_label: str | None = None, reward_label: str | None = None, id_label: str | None = None, T_label: str | None = None, **to_csv_kwargs) → None

Export trajectories from Trajectory Arrays to a .csv file.

The output .csv follows the format specified in the “Tabular Trajectory Data” document of the “Inputs and Outputs” section. The output .csv will also contain a column that records the time steps of each row, where the time steps start from 1.

Args:

path:

The path that specifies where the trajectory should be exported.

zs (list or np.ndarray):

The observed sensitive attributes of each individual in the trajectory. It should be a list or array following the Sensitive Attributes Format.

states (list or np.ndarray):

The state trajectory. It should be a list or array following the Full-trajectory States Format.

actions (list or np.ndarray):

The action trajectory. It should be a list or array following the Full-trajectory Actions Format.

rewards (list or np.ndarray):

The reward trajectory. It should be a list or array following the Full-trajectory Actions Format.

ids (list or np.ndarray):

The IDs of each individual in the trajectory. It is an array with size (N, 1) where N is the number of individuals in the trajectory. Specifically, ids[i, 0] contains the ID of the i-th individual in the trajectory.

z_labels (list[str], optional):

A list of strings representing the labels of columns in the output dataframe that should contain sensitive attribute variables. When set to None, the function will use default names z1, z2, … That is, the i-th component of the sensitive attribute vector will be named zi.

state_labels (list[str]):

A list of strings representing the labels of columns in the output dataframe that should contain state variables. When set to None, the function will use default names state1, state2, … That is, the i-th component of the state vector will be named statei.

action_label (str):

The label of the column in the output dataframe that should contain actions. When set to None, the column that contains actions will be named action by default.

reward_label (str):

The label of the column in the output dataframe that should contain rewards. When set to None, the column that contains rewards will be named reward by default.

id_label (str):

The label of the column in output dataframe that should contain IDs. When set to None, the column that contains IDs will be named ID by default.

T_label (str):

The label of the column in output dataframe that should contain time steps. When set to None, the column that contains time steps will be named timestamp by default.

**to_csv_kwargs:

Additional arguments that specifies details about the expored .csv file. These arguments can be any legit arguments to the pandas.to_csv() function, and they will serve the same functionalities as they do for the pandas.to_csv() function.

pycfrl.reader.reader.read_trajectory_from_csv(path: str, z_labels: list[str], state_labels: list[str], action_label: str, reward_label: str, id_label: str, T: int) → tuple[ndarray, ndarray, ndarray, ndarray, ndarray]

Read tabular trajectory data from a .csv file into Trajectory Arrays.

The .csv file must be in the format specified in the “Tabular Trajectory Data” document of the “Inputs and Outputs” section.

Args:

path (str):

The path to the .csv file.

z_labels (list[str]):

A list of strings representing the labels of columns in the .csv file that contain sensitive attribute variables.

state_labels (list[str]):

A list of strings representing the labels of columns in the .csv file that contain state variables.

action_label (str):

The label of the column in the .csv file that contains actions.

reward_label (str):

The label of the column in the .csv file that contains rewards.

id_label (str):

The label of the column in the .csv file that contains IDs.

T:

The total number of transitions to be read for each individual.

Returns:

zs (np.ndarray):

The observed sensitive attributes of each individual in the trajectory read from the .csv file. It is an array following the Sensitive Attributes Format.

xs (np.ndarray):

The state trajectory read from the .csv file. It is an array following the Full-trajectoriy States Format.

actions (np.ndarray):

The action trajectory read from the .csv file. It is an array following the Full-trajectory Actions Format.

rewards (np.ndarray):

The reward trajectory read from the .csv file. It is an array following the Full-trajectory Rewards Format.

ids (np.ndarray):

The ids of each individual in the trajectory read from the .csv file. It is an array with size (N, 1) where N is the number of individuals in the trajectory. Specifically, ids[i, 0] contains the ID of the i-th individual in the trajectory.

pycfrl.reader.reader.read_trajectory_from_dataframe(data: DataFrame, z_labels: list[str], state_labels: list[str], action_label: str, reward_label: str, id_label: str, T: int) → tuple[ndarray, ndarray, ndarray, ndarray, ndarray]

Read tabular trajectory data from a pandas.DataFrame into Trajectory Arrays.

The dataframe must be in the format specified in the “Tabular Trajectory Data” document of the “Inputs and Outputs” section.

Args:

data (pandas.DataFrame):

The dataframe to read data from.

z_labels (list[str]):

A list of strings representing the labels of columns in the .csv file that contain sensitive attribute variables.

state_labels (list[str]):

A list of strings representing the labels of columns in the .csv file that contain state variables.

action_label (str):

The label of the column in the .csv file that contains actions.

reward_label (str):

The label of the column in the .csv file that contains rewards.

id_label (str):

The label of the column in the .csv file that contains IDs.

T:

The total number of transitions to be read for each individual.

Returns:

zs (np.ndarray):

The observed sensitive attributes of each individual in the trajectory read from the .csv file. It is an array following the Sensitive Attributes Format.

xs (np.ndarray):

The state trajectory read from the .csv file. It is an array following the Full-trajectoriy States Format.

actions (np.ndarray):

The action trajectory read from the .csv file. It is an array following the Full-trajectory Actions Format.

rewards (np.ndarray):

The reward trajectory read from the .csv file. It is an array following the Full-trajectory Rewards Format.

ids (np.ndarray):

The IDs of each individual in the trajectory read from the .csv file. It is an array with size (N, 1) where N is the number of individuals in the trajectory. Specifically, ids[i, 0] contains the ID of the i-th individual in the trajectory.