Add @byrow attempt 2

docs/src/index.md

@@ -268,6 +268,178 @@ df2 = @eachrow df begin
 end
 ```
 
+## Row-wise transformations with `@byrow`
+
+DataFrames provides the function-wrapper `ByRow`. `ByRow(f)(x, y)`
+is roughly equivalent to `f.(x, y)`, with a few exceptions discussed below. 
+DataFramesMeta allows for users to construct expressions using `ByRow` 
+function wrapper with the syntax `@byrow`. 
+
+```julia
+@transform(df, y = @byrow :x == 1 ? "true" : "false)
+```
+
+becomes
+
+```
+transform(df, :x => ByRow(x -> x == 1 ? "true", "false") => :y)
+```
+
+!!! note 
+    Unlike `@.`, `@byrow` is not a "real" macro and cannot be used outside of 
+    DataFramesMeta macros. However it's behavior within DataFramesMeta 
+    macros should be indistinguishable from externally defined macros. 
+
+### Comparison with `@eachrow`
+
+In previous versions of DataFramesMeta, `@eachrow` was named `@byrow`. 
+This version of `@byrow` is deprecated, but the syntax can be used
+to for similar, but not identical, behavior.
+
+The syntax 
+
+```julia
+@eachrow df begin 
+    :a * :b
+end 
+```
+
+is similar to 
+
+```julia
+begin
+    function tempfun(a, b)
+        for i in eachindex(a)
+            a[i] * b[i]
+        end
+    end
+    tempfun(df.a, df.b)
+    df
+end
+```
+
+The function `*` is applied by-row. But the result of those operations
+is not stored in a new vector. Additionally, `@eachrow` and `@eachrow!`
+return data frames. 
+
+By contrast,
+
+```julia
+@with df @byrow begin 
+    :a * :b
+end
+```
+
+is similar to 
+
+```julia
+tempfun(a, b) = a * b
+tempfun.(df.a, df.b)
+```
+
+`@with` combined with `@byrow` will return a vector of the 
+broadcasted multiplication and not a data frame.
+
+Additionally, `@eachrow` and `@eachrow!` allow modifying a data
+data frame. Just as with Base Julia broadcasting, `@byrow` will
+not update columns. 
+
+```
+julia> df = DataFrame(a = [1, 2], b = [3, 4]);
+
+julia> @with df @byrow begin 
+           :a = 500
+       end
+2-element Vector{Int64}:
+ 500
+ 500
+
+julia> df
+2×2 DataFrame
+ Row │ a      b     
+     │ Int64  Int64 
+─────┼──────────────
+   1 │     1      3
+   2 │     2      4
+```
+
+### Comparison with `@.` and Base broadcasting
+
+Base Julia provides the broadasting macro `@.` and in many cases `@.` 
+and `@byrow` will give equivalent results. But there are important 
+deviations in behavior. Consider the setup 
+
+```julia
+df = DataFrame(a = [1, 2], b = [3, 4])
+```
+
+* Control flow. In all versions of Julia, expressions of the form 
+`if...else`, `a ? b : c` cannot be broadcasted. In versions below
+1.7-dev, expressions of the form `a && b` and `a || b` cannot be 
+broadcasted. Consequently, the `@.` macro will fail when encountering such
+control flow while `@byrow` will not. 
+```
+julia> @with df @byrow begin 
+           if :a == 1
+               5
+           else 
+               10
+           end
+       end
+2-element Vector{Int64}:
+  5
+ 10
+
+julia> @with df @. begin 
+           if :a == 1
+               5
+           else 
+               10
+           end
+       end # will error
+```
+
+* Broadcasting objects that are not columns. `@byrow` constructs an 
+anonymous function *which accepts only the columns of the dataframe*
+and broadcasts that function. Consequently, it does not broadcast
+objects that are referenced which are not columns. 
+```julia
+@with df @byrow :x + [5, 6]
+```
+will error. On the other hand
+```julia
+@with df @. :x + [5, 6]
+```
+will not. 
+
+* Broadcasting expensive calls. In Base Julia, broadcastsing 
+evaluates calls first and then broadcasts the result. Because
+`@byrow` constructs an anonymous function and evaluates
+that function for every row in the DataFrame, expensive functions
+will be evaluated many times. 
+```julia
+julia> function expensive()
+           sleep(.5)
+           return 1
+       end;
+
+julia> @time @with df @byrow :a + expensive();
+  1.037073 seconds (51.67 k allocations: 3.035 MiB, 3.19% compilation time)
+
+julia> @time @with df :a .+ expensive();
+  0.539900 seconds (110.67 k allocations: 6.525 MiB, 7.05% compilation time)
+
+```
+This problem comes up when using the `@.` macro as well, but can easily be fixed with `$`.
+```julia
+julia> @time @with df @. :a + expensive();
+  1.036888 seconds (97.55 k allocations: 5.617 MiB, 3.20% compilation time)
+
+julia> @time @with df @. :a + $expensive();
+  0.537961 seconds (110.68 k allocations: 6.525 MiB, 6.73% compilation time)
+```
+No such solution currently exists with `@byrow`. 
+
 ## Working with column names programmatically with `cols`
 
 DataFramesMeta provides the special syntax `cols` for referring to 

src/DataFramesMeta.jl

@@ -8,7 +8,7 @@ using Reexport
 export @with, @where, @orderby, @transform, @by, @combine, @select,
        @transform!, @select!,
        @eachrow, @eachrow!,
-       @byrow, @byrow!, @based_on # deprecated
+       @based_on # deprecated
 
 
 global const DATAFRAMES_GEQ_22 = isdefined(DataFrames, :pretty_table) ? true : false

src/eachrow.jl

@@ -70,27 +70,6 @@ function eachrow_helper(df, body, deprecation_warning)
     end
 end
 
-"""
-    @byrow!(d, expr)
-
-Deprecated version of `@eachrow`, see: [`@eachrow`](@ref)
-
-Acts the exact same way. It does not change the input argument `d` in-place.
-"""
-macro byrow!(df, body)
-    esc(eachrow_helper(df, body, true))
-end
-
-"""
-    @byrow(d, expr)
-
-Deprecated version of `@eachrow`, see: [`@eachrow`](@ref)
-
-Acts the exact same way.
-"""
-macro byrow(d, body)
-    esc(eachrow_helper(d, body, true))
-end
 
 """
     @eachrow(df, body)