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.DataFrameConvert 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:
fieldsis one name:panel_frame_fieldgives that Panel Field as one row per observation and one column per asset. ATensorPanelFieldhas a third axis, so this shape refuses it.layout = :long:panel_frame_longgives one row per pair of observation and asset in the universe. Each Panel Field column is one table column.layout = :wide:panel_frame_widegives 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
- Check
layout. - Name the axes with
panel_frame_axes. The asset names arenx, or the positions"1","2", … whennxisnothing. The observation labels arets, or the positions1,2, … whentsisnothingor the panel is static. Check each length against the axes of the panel. - Find the positions of the selected assets with
panel_frame_assets. fieldsis one string: write that Panel Field withpanel_frame_field, and return the table.- Otherwise find the Panel Fields with
panel_frame_fields, and write them withpanel_frame_longorpanel_frame_wide.
Arguments
pnl: The Asset Panel.nx: The asset names of the universe of the panel, ornothingto name each asset by its position. SeeVecStr.ts: The observation labels, ornothingto 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, ornothingfor all Panel Fields of the panel.assets: One asset label as a string, a collection of labels, ornothingfor all assets of the universe.layout::Symbol = :long::longfor one row per pair of observation and asset in the universe.:widefor 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 whenfieldsnames one Panel Field.decode::Bool = true: Whether aCategoricalPanelFieldgives its levels in place of its integer codes. To read the table back, give the samedecodetopanel_manifest.
Validation
layoutis:longor:wide. Raises anArgumentError.length(nx)is the length of the asset axis of the panel. Raises aDimensionMismatch.length(ts)is the length of the observation axis of the panel, when the panel is time-varying. Raises aDimensionMismatch.- The panel holds every named Panel Field, and
nxholds every named asset. Raises aKeyError. - No asset is named twice in
assets. Raises anArgumentError. fieldsnames noTensorPanelFieldas one string. Raises anArgumentError.- No two columns of the table get the same name. Raises an
ArgumentError. Seepanel_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 TechRelated