Input and output

fdatools.io: conversion to and from pandas and xarray (the pandas extra), and reading R .rds files that hold fd, bifd or basisfd objects (the io extra).

Interoperability with pandas, xarray and R's saveRDS format.

pandas, xarray and rdata are optional dependencies (extras pandas/io): every function here imports them lazily and raises a clear :class:ImportError if the extra is missing, so importing :mod:fdatools itself never requires them.

LongData dataclass

LongData(
    t: dict[str, NDArray[float64]] | NDArray[float64],
    y: dict[str, NDArray[float64]] | NDArray[float64],
    ids: list[str],
)

Per-curve arrays recovered from a long-format table.

Attributes:

Name	Type	Description
t	dict of str to ndarray, or ndarray	Argument values for each curve. A dict keyed by curve id when curves do not share a grid (the irregular path); a single 1-D array, shared by every curve, when they do.
y	dict of str to ndarray, or ndarray, shape (n_t, n_curves)	Observed values, laid out the same way as t: one array per curve id for the irregular path, or a single 2-D array (argument x curve) when the grid is shared.
ids	list of str	Curve ids, in first-seen order.

from_pandas

from_pandas(
    df: DataFrame, id_col: str, t_col: str, y_col: str
) -> LongData

Reshape a long-format :class:pandas.DataFrame into per-curve arrays.

Parameters:

Name	Type	Description	Default
df	DataFrame	One row per (curve, argument value) observation.	required
id_col	str	Column identifying which curve a row belongs to.	required
t_col	str	Column holding the argument value.	required
y_col	str	Column holding the observed value.	required

Returns:

Type	Description
LongData	When every curve has the same, identically-ordered t_col values, t is one shared 1-D array and y one 2-D array (argument x curve); otherwise both are dicts of per-curve 1-D arrays (curves may then have different lengths).

Raises:

Type	Description
ValueError	If any of id_col, t_col, y_col is missing from df, or df has no rows.

Examples:

>>> import pandas as pd
>>> import fdatools as fdt
>>> df = pd.DataFrame(
...     {"id": ["a", "a", "b", "b"], "t": [0.0, 1.0, 0.0, 1.0], "y": [1.0, 2.0, 3.0, 4.0]}
... )
>>> long = fdt.from_pandas(df, "id", "t", "y")
>>> long.ids
['a', 'b']
>>> long.t.shape
(2,)
>>> long.y.shape
(2, 2)

to_pandas

to_pandas(fd: FData, t: Any) -> pd.DataFrame

Evaluate fd on t and return a long-format :class:pandas.DataFrame.

Parameters:

Name	Type	Description	Default
fd	FData	The curves to evaluate.	required
t	array_like	Argument values to evaluate at.	required

Returns:

Type	Description
DataFrame	One row per (t, curve[, var]) combination, with columns t, curve (integer curve index), value and, when fd.n_vars > 1, var.

Examples:

>>> import numpy as np
>>> import fdatools as fdt
>>> fd = fdt.FData(np.eye(4), fdt.BSpline(domain=(0.0, 1.0), n_basis=4))
>>> df = fdt.to_pandas(fd, np.array([0.0, 1.0]))
>>> list(df.columns)
['t', 'curve', 'value']

to_xarray

to_xarray(fd: FData, t: Any) -> xr.DataArray

Evaluate fd on t and return an :class:xarray.DataArray.

Parameters:

Name	Type	Description	Default
fd	FData	The curves to evaluate.	required
t	array_like	Argument values to evaluate at.	required

Returns:

Type	Description
DataArray	Dims ("t", "curve"), or ("t", "curve", "var") when fd.n_vars > 1, coordinated on t.

Examples:

>>> import numpy as np
>>> import fdatools as fdt
>>> fd = fdt.FData(np.eye(4), fdt.BSpline(domain=(0.0, 1.0), n_basis=4))
>>> da = fdt.to_xarray(fd, np.array([0.0, 1.0]))
>>> da.dims
('t', 'curve')

read_rds

read_rds(path: Any) -> Basis | FData | BiFData

Read an R .rds file holding a basisfd, fd or bifd object.

Parameters:

Name	Type	Description	Default
path	str or Path	Path to the .rds file, as written by R's saveRDS().	required

Returns:

Type	Description
Basis or FData or BiFData	Depending on which of the three R classes was stored.

Raises:

Type	Description
ValueError	If the stored R object's class is not one of basisfd, fd or bifd, or it uses a basis feature fdatools does not support (dropind, or a basis type outside bspline/fourier/monomial/power/expon/const/polygonal).

Examples:

>>> import fdatools as fdt
>>> basis = fdt.read_rds("tests/fixtures/bspline_basis.rds")