----------------------------------------------------------------------
This is the API documentation for the hfpca library.
----------------------------------------------------------------------


## Main function

Run the high-frequency PCA algorithm


pca_high_freq(X: NDArray[numpy.number], k: int | None = None, u: NDArray[numpy.number] | None = None, evectors_start: NDArray[numpy.number] | None = None, quiet: bool = False) -> hfpca._core.PCAHighFreqResult

Run high-frequency PCA on a data matrix.

This function implements the algorithm proposed by [Aït-Sahalia and Xiu
(2019)](https://www.nber.org/system/files/working_papers/w21584/w21584.pdf),
returning the time series of principal components, eigenvalues, and
eigenvectors.

A summary of the algorithm's hypothesis and parametrization can be found in
this package's documentation.

Args:
    X: Input data array with shape `(T, d)`, where `T` is the number of
        observations and `d` is the number of variables. Must not contain
        `npnan` or `np.inf` values.
    k: Block size used for the high-frequency PCA routine. If `None`,
        it is chosen by a rule-of-thumb. Must be smaller than `d`
    u: Jump truncation cutoffs for each variable, with shape `(d,)`. If
        `None`, it is chosen by a rule-of-thumb. Must not contain
        `npnan`, `np.inf`, or nonpositive values.
    evectors_start: Optional initial eigenvector matrix with shape `(d, d)`
        used to warm-start the iteration. If not supplied, the first block
        of the results will be `np.nan`.
    quiet: If ``True``, suppress progress prints during computation.

Returns:
    A [`PCAHighFreqResult`][hfpca.types.PCAHighFreqResult] object containing
    the the PCs (`.pcs`), eigenvalue estimates (`.evalues`), eigenvector
    estimates (`.evectors`), which can be unpacked into variables. Also
    contains: the values of `k` (`.k`), `u` (`.u`), and `d` (`.d`); and
    methods for extracting PCs, eigenvalues, and eigenvectors as polars
    dataframes (`.pcs_as_polars()`). See the class documentation for more
    details.

Raises:
    TypeError: If `X`, `u`, or `evectors_start` are not numpy arrays; if
        they do not have a numeric dtype; or if `k` is not an integer.
    ValueError: If `X` is not 2D, or if `u` or `evectors_start` do not have
        the correct dimensions; if any of the inputs contain NaN or Inf
        values; if `u` contains nonpositive values; or if `k` is smaller
        than `d` or larger than `T`.

pca_start_evectors(X: NDArray[numpy.number], k: int | None = None, u: NDArray[numpy.number] | None = None, quiet: bool = True) -> NDArray[numpy.number]

Calculate the starting eigenvectors for the high-frequency PCA routine.

Function is being questioned. Will probably be moved inside `pca_high_freq`.


## Analysis functions

Analyze the results


plot_loadings(pca: hfpca._core.PCAHighFreqResult, exp: float = 1, merge_blocks: int = 1) -> plotnine.ggplot.ggplot

Plot the loading contribution between variables and principal components over time.

The absolute loadings are normalized to `[0-1]` each block-variable pair.
Then, in a pannel for each original variable, a plot of the time serie of
loadings for each principal component is plotted. This shows how a variable
contributed to each PC over time. A high contribution to the first PCs
indicates high variance explanatory power.

Example with high-frequency factor zoo data from [Aleti
2022](https://dx.doi.org/10.2139/ssrn.4021620):

![](../.assets/plot_loadings.png)

Args:
    pca: The result of `pca_high_freq`.
    exp: Exponent applied to the absolute loadings before normalization.
        Higher values emphasize the dominant loading components.
    merge_blocks: Number of blocks to merge (sum) in a single observation
        for plotting. This is useful to reduce the number of points in the
        plot and improve visibility.

Returns:
    A [ggplot][plotnine.ggplot] object. Print the object to show the plot,
    or save it with `plotnine.ggsave`. Modifications can be made by adding
    plotnine calls to the result: `plot_loadings(...) + plotnine.*(...)`.

plot_pcs(pca: hfpca._core.PCAHighFreqResult, merge_blocks: int = 1) -> plotnine.ggplot.ggplot

Plot the principal component trajectories colored by explained variance.

Example with high-frequency factor zoo data from [Aleti
2022](https://dx.doi.org/10.2139/ssrn.4021620):

![](../.assets/plot_pcs.png)

Args:
    pca: The result of `pca_high_freq`.
    merge_blocks: Number of blocks to merge (sum) in a single observation
        for plotting. This is useful to reduce the number of points in the
        plot and improve visibility.

Returns:
    A [ggplot][plotnine.ggplot] object. Print the object to show the plot,
    or save it with `plotnine.ggsave`. Modifications can be made by adding
    plotnine calls to the result: `plot_loadings(...) + plotnine.*(...)`.

quantiles_cut(X: NDArray[numpy.number], pca: hfpca._core.PCAHighFreqResult) -> NDArray[numpy.number]

Compute the fraction of values above the PCA cutoff per feature.

Args:
    X: Input data array with shape `(T, d)`, as passed to `pca_high_freq`.
    pca: the result of `pca_high_freq`.

Returns:
    The fraction of values above the cutoff with shape `(d,)`.