PropertyFunctions

Provides functionality for easy access to and efficient broadcasting over properties.

PropSelFunction{src_names,trg_names} <: PropertyFunction

A special kind of PropertyFunction that selects (and possibly renames) properties, but does no other computations.

A PropSelFunction can be constructed via the @pf macro

propsel = @pf (;$c, d = $a)

or directly via

propsel = PropSelFunction(:c, :a => :d)

or

propsel = PropSelFunction{(:c, :a), (:c, :d)}()

or just

PropSelFunction{(:c, :a)}()

if no property name mapping is required.

Source names may also be paths of nested property names, e.g. in @pf (;$(a.b)).

See also @pf.

struct PropertyFunction <: Function

Use only for dispatch in special cases. User code should not create instances of PropertyFunction directly - use the @pf or @fp macros instead.

The type parameters of PropertyFunction are subject to change and not part of the public API of the PropertyFunctions package.

@fp expression

Like @pf, but with the inverse $ convention: plain symbols in value positions refer to properties of the function argument, while $-escaped symbols and expressions refer to the surrounding scope. Function names and other non-value positions are never treated as properties.

@fp(a + f(b) + $c) is equivalent to @pf($a + f($b) + c).

Nested properties are referenced via plain a.b.c chains.

Note that functions passed as arguments are in value position and so must be $-escaped: @fp foldl($+, a).

@pf expression

Generates a function that accesses the properties of its argument referenced via $property in expression.

@pf($a + $c^2) is equivalent to x -> x.a + x.c^2.

Nested properties can be referenced via $a.b.c or $(a.b.c), and broadcasting will read only the required nested columns (see PropertyFunctions.subcolumn).

Examples:

xs = StructArrays.StructArray((
    a = [0.9, 0.1, 0.9, 0.2, 0.7, 0.0, 0.7, 0.5, 0.2, 0.6],
    b = [0.1, 0.5, 0.9, 0.9, 0.9, 0.6, 0.1, 0.9, 0.8, 0.2],
    c = [0.4, 0.1, 0.4, 0.1, 0.9, 0.2, 0.4, 0.8, 0.0, 0.1]
))

@pf($a + $c^2)(xs[1])
xs .|> @pf $a + $c^2

Functions generated by @pf come with broadcasting specializations that try to ensure that only the columns referenced via $colname in expr will be read, reducing memory traffic. So data.b will not be accessed in the example above. If the broadcasted function generates structs (including NamedTuples), broadcasting specialization will try to return a StructArrays.StructArray.

Property functions of the kind

propsel = @pf (;$c, d = $a)

(or equivalently @pf (c = $c, d = $a)) can be used to select (and rename) properties, and they have special broadcasting optimizations for table-like arguments. This can make broadcasts of such property selectors zero-copy O(1) operations:

new_xs = propsel.(xs)
new_xs.c === xs.c
new_xs.d === xs.a

@pf is also very handy in sortby and filterby:

xs |> sortby(@pf $a + $c^2)
xs |> filterby(@pf $a + $c^2 < 0.5)

filterby([getindex|view,] f)

Generates a function that filters a table-like array by f, returning either a copy (default) or a view (ignored if the object does not support views).

The generated function also accepts unmaterialized broadcasts (Base.Broadcast.Broadcasted) and evaluates f on them in a fused fashion.

Example:

xs = [0.9, 0.1, 0.9, 0.2, 0.7, 0.0, 0.7, 0.5, 0.2, 0.6]
xs |> filterby(x -> x < 0.5)

innermerge(tbl, tbls...)

Merge the columns of table-like objects, with columns of later tables taking precedence (like merge for NamedTuples).

Tries to preserve the table type of tbl, but returns a StructArrays.StructArray where the result would otherwise be a row-oriented table.

Example:

xs = StructArrays.StructArray((a = [1, 2], b = [3, 4]))
ys = innermerge(xs, (c = [5, 6],))
ys.a === xs.a

innermerge may be specialized for table types with expensive column access (e.g. lazy or on-disk tables).

sortby(
    [getindex|view,]
    f;
    rev::Bool = false,
)

Generates a function that sorts an array by f, returning either a copy (default) or a view (ignored if the object does not support views).

The generated function also accepts unmaterialized broadcasts (Base.Broadcast.Broadcasted) and evaluates f on them in a fused fashion.

Example:

xs = [0.9, 0.1, 0.9, 0.2, 0.7, 0.0, 0.7, 0.5, 0.2, 0.6]
xs |> sortby(x -> (x - 0.5)^2)

PropertyFunctions.subcolumn(col::AbstractArray, name::Symbol)

Get the column name of an array col of structs.

Returns getproperty.(col, name) by default, StructArray columns provide zero-copy access. Specialize for array types that support efficient column access.

subst_prop_refs(expr)

Replace $-escaped property references in expr by property accesses on a generated argument name and return the referenced properties, the argument name and the modified expression.

Usage:

props, argsym, new_expr = subst_prop_refs(expr)