Panel data frame

PortfolioOptimisers.panel_dataframe — Function
panel_dataframe(pnl::AssetPanel; nx::Option{<:VecStr} = nothing,
                ts::Option{<:AbstractVector} = nothing, fields = nothing,
                assets = nothing, layout::Symbol = :long,
                decode::Bool = true) -> DataFrames.DataFrame

Convert an AssetPanel to a DataFrames.DataFrame.

The library has no file format for a panel. To save, plot or share a panel, convert it to a table with this function, and write the table with a package that reads a DataFrame, for example CSV.jl or Arrow.jl. To read the panel back, write its manifest from panel_manifest beside the table, and give both tables to asset_panel, the inverse of this function. The long layout drops the cells outside the universe, and the wide layout keeps every cell:

CSV.write("panel.csv", panel_dataframe(pnl; nx, ts, layout = :wide))CSV.write("manifest.csv", panel_manifest(pnl; nx, ts))pnl2 = asset_panel(DataFrame(CSV.File("panel.csv")), DataFrame(CSV.File("manifest.csv")))

The panel holds no asset names and no observation labels, because the PricesResult or the ReturnsResult that holds the panel names them. So the caller gives them in nx and ts. When one of them is nothing, the table names each entry by its position on the axis.

The table has one of three shapes:

  • fields is one name: panel_frame_field gives that Panel Field as one row per observation and one column per asset. A TensorPanelField has a third axis, so this shape refuses it.
  • layout = :long: panel_frame_long gives one row per pair of observation and asset in the universe. Each Panel Field column is one table column.
  • layout = :wide: panel_frame_wide gives one row per observation and one column per pair of Panel Field column and asset. It keeps every cell and both universe masks.

In both layouts a tensor Panel Field gives one column per label-axis label, with the "<field>=<label>" name that the label has in a Feature Matrix.

Algorithm

  1. Check layout.
  2. Name the axes with panel_frame_axes. The asset names are nx, or the positions "1", "2", … when nx is nothing. The observation labels are ts, or the positions 1, 2, … when ts is nothing or the panel is static. Check each length against the axes of the panel.
  3. Find the positions of the selected assets with panel_frame_assets.
  4. fields is one string: write that Panel Field with panel_frame_field, and return the table.
  5. Otherwise find the Panel Fields with panel_frame_fields, and write them with panel_frame_long or panel_frame_wide.

Arguments

  • pnl: The Asset Panel.
  • nx: The asset names of the universe of the panel, or nothing to name each asset by its position. See VecStr.
  • ts: The observation labels, or nothing to name each observation by its position. A static panel has no observation axis and does not read it.
  • fields: One Panel Field name as a string, a collection of names, or nothing for all Panel Fields of the panel.
  • assets: One asset label as a string, a collection of labels, or nothing for all assets of the universe.
  • layout::Symbol = :long: :long for one row per pair of observation and asset in the universe. :wide for one row per observation and one column per pair of Panel Field column and asset. The function checks it in every call, and does not use it when fields names one Panel Field.
  • decode::Bool = true: Whether a CategoricalPanelField gives its levels in place of its integer codes. To read the table back, give the same decode to panel_manifest.

Validation

  • layout is :long or :wide. Raises an ArgumentError.
  • length(nx) is the length of the asset axis of the panel. Raises a DimensionMismatch.
  • length(ts) is the length of the observation axis of the panel, when the panel is time-varying. Raises a DimensionMismatch.
  • The panel holds every named Panel Field, and nx holds every named asset. Raises a KeyError.
  • No asset is named twice in assets. Raises an ArgumentError.
  • fields names no TensorPanelField as one string. Raises an ArgumentError.
  • No two columns of the table get the same name. Raises an ArgumentError. See panel_frame_column!.

Returns

  • df::DataFrames.DataFrame: The table. It holds copies, so a change to the table does not change the panel.

Examples

julia> pnl = AssetPanel(;                        pf = [NumericPanelField(; name = "mcap", vals = [1.0, 2.0, 3.0]),                              CategoricalPanelField(; name = "sector", levels = ["Tech", "Energy"],                                                    codes = [1, 2, 1])]);julia> panel_dataframe(pnl; nx = ["A", "B", "C"])3×3 DataFrame Row │ asset   mcap     sector     │ String  Float64  String─────┼─────────────────────────   1 │ A           1.0  Tech   2 │ B           2.0  Energy   3 │ C           3.0  Tech

Related

source