Panel field values

panel_field_values(pnl::AssetPanel, name::AbstractString;
                   inactive::Option{<:Real} = nothing,
                   unobserved::Option{<:Real} = NaN) -> AbstractArray
panel_field_values(rd::ReturnsResult, name::AbstractString;
                   inactive::Option{<:Real} = nothing,
                   unobserved::Option{<:Real} = NaN) -> AbstractArray

Read the values of one Panel Field, with a policy for its inactive cells and a policy for its unobserved cells.

An AssetPanel keeps a finite value in every cell of a numeric Panel Field. The two universe masks say which cells are in the universe, and the observed mask of the field says which cells a fill policy wrote. A consumer reads the masks, so it never needs a marker in the values. A caller who wants the marker, for example to hand the values to code that reads no mask, chooses it here at read time. Nothing is stored, and the panel does not change.

A policy is a value or nothing:

• inactive = NaN writes NaN into every cell where the active mask is false. This is the usual convention that a cell outside the universe is missing.
• inactive = 0 writes a zero there.
• inactive = nothing keeps the stored value.

unobserved takes the same forms for the cells whose observed mask is false, and its default NaN shows where the data held a blank. A cell that is both inactive and unobserved takes the inactive policy when that policy is not nothing, because the asset is outside the universe whatever the data held. On a static panel no cell is inactive.

The same rule reads all three kinds of Panel Field. A TensorPanelField writes the policy into every label of an inactive observation and asset. A CategoricalPanelField reads its integer codes, so inactive = CS_MISSING_GROUP marks an inactive cell with the code of a missing group, and inactive = NaN gives floating-point codes with NaN there.

The element type of the answer comes from the stored type and the two policies, through panel_read_eltype. An integer field read with a NaN policy is floated, and every other type is kept: an integer field read with inactive = 0 and unobserved = nothing stays an integer field.

Algorithm

1. Look the Panel Field up by name through panel_field, and read its stored array through panel_field_array.
2. Copy the array into the element type that holds both policies.
3. Write unobserved into every cell whose observed mask is false, through panel_read_write!.
4. Write inactive into every cell whose active mask is false. This step runs last, so it decides a cell that is both.
5. For a ReturnsResult, read the Asset Panel it holds in rd.pnl by steps 1 to 4.

Arguments

• pnl: The Asset Panel.
• rd: The returns result to use. It must carry an Asset Panel in rd.pnl.
• name: The Panel Field's name.
• inactive: The value for a cell outside the universe, or nothing to keep the stored value.
• unobserved: The value for a cell that a fill policy wrote, or nothing to keep the fill value.

Validation

• The panel holds a Panel Field named name. Raises a KeyError.
• rd.pnl is an AssetPanel. Raises an IsNothingError.
• A policy value converts to the element type of the answer. An integer field read with inactive = 0.5 is floated, and a Rational field read with NaN raises an InexactError at the first cell that the policy writes.

Returns

• V::AbstractArray: A copy of the values, with the shape of the Panel Field: assets or observations × assets, with a trailing label axis on a tensor Panel Field.

Examples

julia> pnl = asset_panel([NumericPanelInput(; name = "mcap", vals = [1 2; 3 4; 5 6])];                         amsk = [true false; true true; true true],                         emsk = [true false; true true; true true]);julia> panel_field_values(pnl, "mcap")3×2 Matrix{Float64}: 1.0  2.0 3.0  4.0 5.0  6.0julia> panel_field_values(pnl, "mcap"; inactive = NaN)3×2 Matrix{Float64}: 1.0  NaN 3.0    4.0 5.0    6.0julia> panel_field_values(pnl, "mcap"; inactive = 0, unobserved = nothing)3×2 Matrix{Int64}: 1  0 3  4 5  6

Related

• panel_field
• AssetPanel
• asset_panel
• panel_dataframe
• descriptor_field_values
• CS_MISSING_GROUP
• Option