Proposal to modify the text of the documentation of DataFrameMacros v0.3.1

[Labejj]

(part: Modifier macros) (https://jkrumbiegel.com/DataFrameMacros.jl/stable/documentation/)

As a beginner user of DataFrames.jl, I appreciate the high intuitiveness of the DataFrameMacros extension and the excellent readability of the generated program code. Commands of the DataFrameMacros extension are easy to learn too. I think it would be useful for novice users to correct and add the following to the documentation:

(Begin of obsolete text) Modifier macros

You can modify the behavior of all macros using modifier macros, which are not real macros but only signal changed behavior for a positional argument to the outer macro.

Each modifier is specified with a single character, and you can combine these characters as well. The supported flags are:

character meaning r Switch to by-row processing. c Switch to by-column processing. m Wrap the function expression in passmissing. t Collect all :symbol = expression expressions into a NamedTuple where (; symbol = expression, ...) and set the sink to AsTable. (End of obsolete text)

(Begin of the proposed text correction) Modifier macros

You can modify the behavior of all macros using modifier macros, which are not real macros but only signal changed behavior for a positional argument to the outer macro.

The supported modifier macros are:

modifier meaning @byrow Switch to by-row processing. @bycol Switch to by-column processing. @passmissing Wrap the function expression in passmissing. @astable Collect all :symbol = expression expressions into a NamedTuple where (; symbol = expression, ...) and set the sink to AsTable.

You can combine these modifiers as well.

Notice of special case: Use of modifier macros in multiple transformation statements separated by commas

Example:

julia> using DataFrames, DataFrameMacros, Chain

julia> df = DataFrame( :a => [1, 2, 3, 4, 5], :b => [1, 2, 3, 4, 5], :c => [2, 4, 6, 8, 10], ) 5×3 DataFrame Row │ a b c │ Int64 Int64 Int64 ─────┼───────────────────── 1 │ 1 1 2 2 │ 2 2 4 3 │ 3 3 6 4 │ 4 4 8 5 │ 5 5 10

This doesn't work

julia> @chain df begin @transform(:d = @bycol sum(:b),:e = @bycol sum(:c)) end ERROR: LoadError: UndefVarError: @bycol not defined

The problem there is that the @bycol macro is applied across the comma that separates your statements. For multiple commands it's therefore easier to list them in a begin end block. Or you wrap the right hand side of @bycol in parentheses. That's a Julia parsing limitation.**

This works

julia> @chain df begin @transform(begin :d = @bycol sum(:b) :e = @bycol sum(:c) end) end

5×5 DataFrame Row │ a b c d e │ Int64 Int64 Int64 Int64 Int64 ─────┼─────────────────────────────────── 1 │ 1 1 2 15 30 2 │ 2 2 4 15 30 3 │ 3 3 6 15 30 4 │ 4 4 8 15 30 5 │ 5 5 10 15 30

This also works

julia> @chain df begin @transform(:d = @bycol(sum(:b)),:e = @bycol(sum(:c)) ) end

(End of the proposed text correction)

[jkrumbiegel]

Oh it seems I just forgot to remove the section on the old flag macros, because it doesn't actually use the macro syntax and didn't turn up when searching for them in the code base.

[jkrumbiegel]

fixed the table