From ad2efbb4119b809e701ab6c8a53399932817edb3 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Tue, 16 Jul 2024 19:33:17 +0000 Subject: [PATCH] build based on 7ea2e2d --- dev/api/api/index.html | 64 +++++++++++++++++++++--------------------- dev/dplyr/index.html | 2 +- dev/index.html | 2 +- dev/search/index.html | 2 +- 4 files changed, 35 insertions(+), 35 deletions(-) diff --git a/dev/api/api/index.html b/dev/api/api/index.html index 77e9ae4..28caef5 100644 --- a/dev/api/api/index.html +++ b/dev/api/api/index.html @@ -30,7 +30,7 @@ │ Column │ Label │ ├────────┼────────────────────────┤ │ wage │ Hourly wage (2015 USD) │ -└────────┴────────────────────────┘source
DataFramesMeta.printnotes — Function
printnotes(df, cols = All(); unnoted = false)

Print the notes and labels in a data frame.

Arguments

  • cols: Optional argument to select columns to print. Can be any valid multi-column selector, such as Not(...), Between(...), or a regular expression.
  • unnoted: Keyword argument for whether to print the columns without user-defined notes or labels.

For the purposes of printing, column labels are printed in addition to notes. However column labels are not returned by note(df, col).

julia> df = DataFrame(wage = [12], age = [23]);
+└────────┴────────────────────────┘
source
DataFramesMeta.printnotes — Function
printnotes(df, cols = All(); unnoted = false)

Print the notes and labels in a data frame.

Arguments

  • cols: Optional argument to select columns to print. Can be any valid multi-column selector, such as Not(...), Between(...), or a regular expression.
  • unnoted: Keyword argument for whether to print the columns without user-defined notes or labels.

For the purposes of printing, column labels are printed in addition to notes. However column labels are not returned by note(df, col).

julia> df = DataFrame(wage = [12], age = [23]);
 
 julia> @label! df :age = "Age (years)";
 
@@ -49,7 +49,7 @@
 
 Column: age
 ───────────
-Label: Age (years)
source
DataFramesMeta.@astable — Macro
@astable(args...)

Return a NamedTuple from a single transformation inside the DataFramesMeta.jl macros, @select, @transform, and their mutating and row-wise equivalents.

@astable acts on a single block. It works through all top-level expressions and collects all such expressions of the form :y = ... or $y = ..., i.e. assignments to a Symbol or an escaped column identifier, which is a syntax error outside of DataFramesMeta.jl macros. At the end of the expression, all assignments are collected into a NamedTuple to be used with the AsTable destination in the DataFrames.jl transformation mini-language.

Concretely, the expressions

df = DataFrame(a = 1)
+Label: Age (years)
source
DataFramesMeta.@astable — Macro
@astable(args...)

Return a NamedTuple from a single transformation inside the DataFramesMeta.jl macros, @select, @transform, and their mutating and row-wise equivalents.

@astable acts on a single block. It works through all top-level expressions and collects all such expressions of the form :y = ... or $y = ..., i.e. assignments to a Symbol or an escaped column identifier, which is a syntax error outside of DataFramesMeta.jl macros. At the end of the expression, all assignments are collected into a NamedTuple to be used with the AsTable destination in the DataFrames.jl transformation mini-language.

Concretely, the expressions

df = DataFrame(a = 1)
 
 @rtransform df @astable begin
     :x = 1
@@ -115,7 +115,7 @@
    1 │     1      5           7      5
    2 │     1      6           8      6
    3 │     2     70          74    140
-   4 │     2     80          84    160
source
DataFramesMeta.@based_on — Macro
@based_on(d, args...)

Deprecated version of @combine, see: @combine

source
DataFramesMeta.@by — Macro
@by(d::AbstractDataFrame, cols, e...; kwargs...)

Split-apply-combine in one step.

Arguments

  • d : an AbstractDataFrame
  • cols : a column indicator (Symbol, Int, Vector{Symbol}, etc.)
  • e : keyword-like arguments, of the form :y = f(:x) specifying

new columns in terms of column groupings

  • kwargs : keyword arguments passed to DataFrames.combine

Returns

  • ::DataFrame or a GroupedDataFrame

Details

Transformation inputs to @by can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, or as a series of keyword-like arguments. For example, the following are equivalent:

@by df :g begin
+   4 │     2     80          84    160
source
DataFramesMeta.@based_on — Macro
@based_on(d, args...)

Deprecated version of @combine, see: @combine

source
DataFramesMeta.@by — Macro
@by(d::AbstractDataFrame, cols, e...; kwargs...)

Split-apply-combine in one step.

Arguments

  • d : an AbstractDataFrame
  • cols : a column indicator (Symbol, Int, Vector{Symbol}, etc.)
  • e : keyword-like arguments, of the form :y = f(:x) specifying

new columns in terms of column groupings

  • kwargs : keyword arguments passed to DataFrames.combine

Returns

  • ::DataFrame or a GroupedDataFrame

Details

Transformation inputs to @by can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, or as a series of keyword-like arguments. For example, the following are equivalent:

@by df :g begin
     :mx = mean(:x)
     :sx = std(:x)
 end

and

@by(df, :g, mx = mean(:x), sx = std(:x))

Transformations can also use the macro-flag @astable for creating multiple new columns at once and letting transformations share the same name-space. See ? @astable for more details.

@by accepts the same keyword arguments as DataFrames.combine and can be added in two ways. When inputs are given as multiple arguments, they are added at the end after a semi-colon ;, as in

@by(ds, :g, :x = first(:a); ungroup = false)

When inputs are given in "block" format, the last lines may be written @kwarg key = value, which indicates keyword arguments to be passed to combine function.

@by df :a begin
@@ -180,7 +180,7 @@
    6 │     3      7      5.0
    7 │     4      4      6.0
    8 │     4      8      6.0
-
source
DataFramesMeta.@byrow — Macro
@byrow

Broadcast operations within DataFramesMeta.jl macros.

@byrow is not a "real" Julia macro but rather serves as a "flag" to indicate that the anonymous function created by DataFramesMeta to represent an operation should be applied "by-row".

If an expression starts with @byrow, either of the form @byrow :y = f(:x) in transformations or @byrow f(:x) in @orderby, @subset, and @with, then the anonymous function created by DataFramesMeta is wrapped in the DataFrames.ByRow function wrapper, which broadcasts the function so that it run on each row.

Examples

julia> df = DataFrame(a = [1, 2, 3, 4], b = [5, 6, 7, 8]);
+
source
DataFramesMeta.@byrow — Macro
@byrow

Broadcast operations within DataFramesMeta.jl macros.

@byrow is not a "real" Julia macro but rather serves as a "flag" to indicate that the anonymous function created by DataFramesMeta to represent an operation should be applied "by-row".

If an expression starts with @byrow, either of the form @byrow :y = f(:x) in transformations or @byrow f(:x) in @orderby, @subset, and @with, then the anonymous function created by DataFramesMeta is wrapped in the DataFrames.ByRow function wrapper, which broadcasts the function so that it run on each row.

Examples

julia> df = DataFrame(a = [1, 2, 3, 4], b = [5, 6, 7, 8]);
 
 julia> @transform(df, @byrow :c = :a * :b)
 4×3 DataFrame
@@ -264,7 +264,7 @@

This problem comes up when using the @. macro as well, but can easily be fixed with $. Because $ is currently reserved for escaping column references, no solution currently exists with @byrow or in DataFramesMeta.jl at large. The best solution is simply

@with df begin
     x = expensive()
     :a + x
-end
source
DataFramesMeta.@combine — Macro
@combine(x, args...; kwargs...)

Summarize a grouping operation

Arguments

  • x : a GroupedDataFrame or AbstractDataFrame
  • args... : transformations defining new columns, of the form :y = f(:x)
  • kwargs: : keyword arguments passed to DataFrames.combine

Results

  • A DataFrame or a GroupedDataFrame

Details

Inputs to @combine can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, or as a series of keyword-like arguments. For example, the following are equivalent:

@combine df begin
+end
source
DataFramesMeta.@combine — Macro
@combine(x, args...; kwargs...)

Summarize a grouping operation

Arguments

  • x : a GroupedDataFrame or AbstractDataFrame
  • args... : transformations defining new columns, of the form :y = f(:x)
  • kwargs: : keyword arguments passed to DataFrames.combine

Results

  • A DataFrame or a GroupedDataFrame

Details

Inputs to @combine can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, or as a series of keyword-like arguments. For example, the following are equivalent:

@combine df begin
     :mx = mean(:x)
     :sx = std(:x)
 end

and

@combine(df, :mx = mean(:x), :sx = std(:x))

Transformations can also use the macro-flag @astable for creating multiple new columns at once and letting transformations share the same name-space. See ? @astable for more details.

@combine accepts the same keyword arguments as DataFrames.combine and can be added in two ways. When inputs are given as multiple arguments, they are added at the end after a semi-colon ;, as in

@combine(gd, :x = first(:a); ungroup = false)

When inputs are given in "block" format, the last lines may be written @kwarg key = value, which indicates keyword arguments to be passed to combine function.

@combine gd begin
@@ -315,7 +315,7 @@
   18 │     3      6     27
   19 │     3      6     27
   20 │     3      6     27
-
source
DataFramesMeta.@distinct! — Macro
@distinct!(d, args...)

In-place selection of unique rows in an AbstractDataFrame. Users should note that @distinct! differs from unique! in DataFrames.jl, such that @distinct!(df, [:x,:y]) is not equal to unique(df, [:x,:y]). See Details for a discussion of these differences.

Arguments

  • d : an AbstractDataFrame
  • args... : transformations of the form :x designating

symbols to specify columns or f(:x) specifying their transformations

Returns

  • ::AbstractDataFrame

Inputs to @distinct! can come in two formats: a begin ... end block, or as a series of arguments and keyword-like arguments. For example, the following are equivalent:

@distinct! df begin 
+
source
DataFramesMeta.@distinct! — Macro
@distinct!(d, args...)

In-place selection of unique rows in an AbstractDataFrame. Users should note that @distinct! differs from unique! in DataFrames.jl, such that @distinct!(df, [:x,:y]) is not equal to unique(df, [:x,:y]). See Details for a discussion of these differences.

Arguments

  • d : an AbstractDataFrame
  • args... : transformations of the form :x designating

symbols to specify columns or f(:x) specifying their transformations

Returns

  • ::AbstractDataFrame

Inputs to @distinct! can come in two formats: a begin ... end block, or as a series of arguments and keyword-like arguments. For example, the following are equivalent:

@distinct! df begin 
     :x .+ :y
 end

and 

@distinct!(df, :x .+ :y)

@distinct! uses the syntax @byrow to wrap transformations in the ByRow function wrapper from DataFrames, apply a function row-wise, similar to broadcasting. @distinct! allows @byrow at the beginning of a block of selections (i.e. @byrow begin... end). The transformation in the block will operate by row. For example, the following two statements are equivalent.

@distinct! df @byrow begin 
     :x + :y
@@ -342,7 +342,7 @@
  Row │ x      y      
      │ Int64  Int64  
 ─────┼───────────────
-   1 │     1      10
source
DataFramesMeta.@distinct — Macro
@distinct(d, args...)

Return the first occurrence of unique rows in an AbstractDataFrame according to given combinations of values in selected columns or their transformation. args can be most column selectors or transformation accepted by select. Users should note that @distinct differs from unique in DataFrames.jl, such that @distinct(df, :x,:y) is not the same as unique(df, [:x,:y]). See Details for a discussion of these differences.

Arguments

  • d : an AbstractDataFrame
  • args... : transformations of the form :x designating

symbols to specify columns or f(:x) specifying their transformations

Returns

  • ::AbstractDataFrame

Inputs to @distinct can come in two formats: a begin ... end block, or as a series of arguments and keyword-like arguments. For example, the following are equivalent:

@distinct df begin 
+   1 │     1      10
source
DataFramesMeta.@distinct — Macro
@distinct(d, args...)

Return the first occurrence of unique rows in an AbstractDataFrame according to given combinations of values in selected columns or their transformation. args can be most column selectors or transformation accepted by select. Users should note that @distinct differs from unique in DataFrames.jl, such that @distinct(df, :x,:y) is not the same as unique(df, [:x,:y]). See Details for a discussion of these differences.

Arguments

  • d : an AbstractDataFrame
  • args... : transformations of the form :x designating

symbols to specify columns or f(:x) specifying their transformations

Returns

  • ::AbstractDataFrame

Inputs to @distinct can come in two formats: a begin ... end block, or as a series of arguments and keyword-like arguments. For example, the following are equivalent:

@distinct df begin 
     :x + :y
 end

and 

@distinct(df, :x + :y)

@distinct uses the syntax @byrow to wrap transformations in the ByRow function wrapper from DataFrames, apply a function row-wise, similar to broadcasting. @distinct allows @byrow at the beginning of a block of selections (i.e. @byrow begin... end). The transformation in the block will operate by row. For example, the following two statements are equivalent.

@distinct df @byrow begin 
     :x + :y
@@ -368,7 +368,7 @@
  Row │ x      y      
      │ Int64  Int64  
 ─────┼───────────────
-   1 │     1      10
source
DataFramesMeta.@eachrow! — Macro
@eachrow!(df, body)

Act on each row of a data frame in-place, similar to

for row in eachrow(df)
+   1 │     1      10
source
DataFramesMeta.@eachrow! — Macro
@eachrow!(df, body)

Act on each row of a data frame in-place, similar to

for row in eachrow(df)
     ... # Actions that modify `df`.
 end

Includes support for control flow and begin end blocks. Since the "environment" induced by @eachrow! df is implicitly a single row of df, use regular operators and comparisons instead of their elementwise counterparts as in @with. Note that the scope within @eachrow! is a hard scope.

eachrow! also supports special syntax for allocating new columns. The syntax @newcol x::Vector{Int} allocates a new uninitialized column :x with an Vector container with eltype Int.This feature makes it easier to use eachrow for data transformations. _N is introduced to represent the number of rows in the data frame, _DF represents the dataframe including added columns, and row represents the index of the current row.

Changes to the rows directly affect df. The operation will modify the data frame in place. See @eachrow which employs the same syntax but allocates a fresh data frame.

Like with @transform!, @eachrow! supports the use of $ to work with column names stored as variables. Using $ with a multi-column selector, such as a Vector of Symbols, is currently unsupported.

@eachrow! is a thin wrapper around a for-loop. As a consequence, inside an @eachrow! block, the reserved-word arguments break and continue function the same as if written in a for loop. Rows unaffected by break and continue are unmodified, but are still present in modified. Also because @eachrow! is a for-loop, re-assigning global variables inside an @eachrow block is discouraged.

Arguments

  • df : an AbstractDataFrame
  • expr : expression operated on row by row

Returns

The modified AbstractDataFrame.

Examples

julia> using DataFramesMeta
 
@@ -460,7 +460,7 @@
            println(:A)
        end;
 1
-3
source
DataFramesMeta.@eachrow — Macro
@eachrow(df, body)

Act on each row of a data frame, producing a new dataframe. Similar to

for row in eachrow(copy(df))
+3
source
DataFramesMeta.@eachrow — Macro
@eachrow(df, body)

Act on each row of a data frame, producing a new dataframe. Similar to

for row in eachrow(copy(df))
     ...
 end

Includes support for control flow and begin end blocks. Since the "environment" induced by @eachrow df is implicitly a single row of df, use regular operators and comparisons instead of their elementwise counterparts as in @with. Note that the scope within @eachrow is a hard scope.

eachrow also supports special syntax for allocating new columns. The syntax @newcol x::Vector{Int} allocates a new uninitialized column :x with an Vector container with eltype Int.This feature makes it easier to use eachrow for data transformations. _N is introduced to represent the number of rows in the data frame, _DF represents the DataFrame including added columns, and row represents the index of the current row.

Changes to the rows do not affect df but instead a freshly allocated data frame is returned by @eachrow. Also note that the returned data frame does not share columns with df. See @eachrow! which employs the same syntax but modifies the data frame in-place.

Like with @transform, @eachrow supports the use of $ to work with column names stored as variables. Using $ with a multi-column selector, such as a Vector of Symbols, is currently unsupported.

@eachrow is a thin wrapper around a for-loop. As a consequence, inside an @eachrow block, the reserved-word arguments break and continue function the same as if written in a for loop. Rows unaffected by break and continue are unmodified, but are still present in the returned data frame. Also because @eachrow is a for-loop, re-assigning global variables inside an @eachrow block is discouraged.

Arguments

  • df : an AbstractDataFrame
  • expr : expression operated on row by row

Returns

The modified AbstractDataFrame.

Examples

julia> using DataFramesMeta
 
@@ -545,11 +545,11 @@
        end;
 1
 3
-
source
DataFramesMeta.@groupby — Macro
groupby(df, args...)

Group a data frame by columns. An alias for

groupby(df, Cols(args...))

but with a few convenience features.

Details

@groupby does not perform any transformations or allow the generation of new columns. New column generation must be done before @groupby is called.

@groupby allows mixing of Symbol and String inputs, such that @groupby df :A "B" is supported.

Arguments are not escaped and DataFramesMeta.jl rules for column selection, such as $ for escaping, do not apply.

Examples

julia> df = DataFrame(A = [1, 1], B = [3, 4], C = [6, 6]);
+
source
DataFramesMeta.@groupby — Macro
groupby(df, args...)

Group a data frame by columns. An alias for

groupby(df, Cols(args...))

but with a few convenience features.

Details

@groupby does not perform any transformations or allow the generation of new columns. New column generation must be done before @groupby is called.

@groupby allows mixing of Symbol and String inputs, such that @groupby df :A "B" is supported.

Arguments are not escaped and DataFramesMeta.jl rules for column selection, such as $ for escaping, do not apply.

Examples

julia> df = DataFrame(A = [1, 1], B = [3, 4], C = [6, 6]);
 julia> @groupby df :A;
 julia> @groupby df :A :B;
 julia> @groupby df [:A, :B];
-julia> @groupby df :A [:B, :C];
source
DataFramesMeta.@kwarg — Macro
@kwarg(args...)

Inside of DataFramesMeta.jl macros, pass keyword arguments to the underlying DataFrames.jl function when arguments are written in "block" format.

julia> df = DataFrame(x = [1, 1, 2, 2], b = [5, 6, 7, 8]);
+julia> @groupby df :A [:B, :C];
source
DataFramesMeta.@kwarg — Macro
@kwarg(args...)

Inside of DataFramesMeta.jl macros, pass keyword arguments to the underlying DataFrames.jl function when arguments are written in "block" format.

julia> df = DataFrame(x = [1, 1, 2, 2], b = [5, 6, 7, 8]);
 
 julia> @rsubset df begin
            :x == 1
@@ -560,7 +560,7 @@
      │ Int64  Int64
 ─────┼──────────────
    1 │     1      5
-   2 │     1      6
Note

This only has meaning inside DataFramesMeta.jl macros. It does not work outside of DataFrames.jl macros.

source
DataFramesMeta.@label! — Macro
@label!(df, args...)

Assign labels to columns in a data frame using :col = label syntax. Shorthand for label!(df, ...) from TablesMetaDataTools.jl.

julia> df = DataFrame(wage = 12);
+   2 │     1      6
Note

This only has meaning inside DataFramesMeta.jl macros. It does not work outside of DataFrames.jl macros.

source
DataFramesMeta.@label! — Macro
@label!(df, args...)

Assign labels to columns in a data frame using :col = label syntax. Shorthand for label!(df, ...) from TablesMetaDataTools.jl.

julia> df = DataFrame(wage = 12);
 
 julia> @label! df :wage = "Wage per hour (USD)";
 
@@ -582,7 +582,7 @@
 ├────────┼────────────────────────┤
 │   wage │    Wage per hour (USD) │
 │ tenure │ Tenure at job (months) │
-└────────┴────────────────────────┘
source
DataFramesMeta.@linq — Macro
@linq df ...
Note

@linq is deprecated. Use @chain instead. See ? @chain for details.

General macro that creates a mini DSL for chaining and macro calls.

Details

The following embedded function calls are equivalent to their macro version:

  • with
  • where
  • select
  • transform
  • by
  • groupby
  • orderby
  • combine

Examples

julia> using DataFramesMeta, Statistics
+└────────┴────────────────────────┘
source
DataFramesMeta.@linq — Macro
@linq df ...
Note

@linq is deprecated. Use @chain instead. See ? @chain for details.

General macro that creates a mini DSL for chaining and macro calls.

Details

The following embedded function calls are equivalent to their macro version:

  • with
  • where
  • select
  • transform
  • by
  • groupby
  • orderby
  • combine

Examples

julia> using DataFramesMeta, Statistics
 
 julia> df = DataFrame(
             a = repeat(1:4, outer = 2),
@@ -613,7 +613,7 @@
 ├─────┼─────────┼─────────┼───────┤
 │ 1   │ 5.0     │ 50.0    │ 2     │
 │ 2   │ 6.0     │ 60.0    │ 1     │
-
source
DataFramesMeta.@note! — Macro
@note!(df, args...)

Assign notes to columns in a data frame using :col = note syntax. Shorthand for note!(df, col, note) from TablesMetadataTools.jl.

Use @note! for longer explanations of columns. Use @label! for short descriptions, primarily for pretty printing.

Returns df, with the notes of df modified.


+
source
DataFramesMeta.@note! — Macro
@note!(df, args...)

Assign notes to columns in a data frame using :col = note syntax. Shorthand for note!(df, col, note) from TablesMetadataTools.jl.

Use @note! for longer explanations of columns. Use @label! for short descriptions, primarily for pretty printing.

Returns df, with the notes of df modified.


 julia> df = DataFrame(wage = 12);
 
 julia> @note! df :wage = "
@@ -645,7 +645,7 @@
 Wage per hour is measured directly for hourly workers. For
 salaried workers, equal to salary / hours worked.
 
-Wage is capped at 99th percentile
source
DataFramesMeta.@orderby — Macro
@orderby(d, i...)

Sort rows by values in one of several columns or a transformation of columns. Always returns a fresh DataFrame. Does not accept a GroupedDataFrame.

Arguments

  • d: a DataFrame or GroupedDataFrame
  • i...: arguments on which to sort the object

Details

When given a DataFrame, @orderby applies the transformation given by its arguments (but does not create new columns) and sorts the given DataFrame on the result, returning a new DataFrame.

Inputs to @orderby can come in two formats: a begin ... end block, in which case each line in the block is a separate ordering operation, and as mulitple arguments. For example, the following two statements are equivalent:

@orderby df begin
+Wage is capped at 99th percentile
source
DataFramesMeta.@orderby — Macro
@orderby(d, i...)

Sort rows by values in one of several columns or a transformation of columns. Always returns a fresh DataFrame. Does not accept a GroupedDataFrame.

Arguments

  • d: a DataFrame or GroupedDataFrame
  • i...: arguments on which to sort the object

Details

When given a DataFrame, @orderby applies the transformation given by its arguments (but does not create new columns) and sorts the given DataFrame on the result, returning a new DataFrame.

Inputs to @orderby can come in two formats: a begin ... end block, in which case each line in the block is a separate ordering operation, and as mulitple arguments. For example, the following two statements are equivalent:

@orderby df begin
     :x
     -:y
 end

and

@orderby(df, :x, -:y)

Arguments

  • d : an AbstractDataFrame
  • i... : expression for sorting

If an expression provided to @orderby begins with @byrow, operations are applied "by row" along the data frame. To avoid writing @byrow multiple times, @orderby also allows @byrowto be placed at the beginning of a block of operations. For example, the following two statements are equivalent.

@orderby df @byrow begin
@@ -724,7 +724,7 @@
    7 │     2      8  h
    8 │     3      1  a
    9 │     3      2  b
-  10 │     3      3  c
source
DataFramesMeta.@passmissing — Macro
@passmissing(args...)

Propagate missing values inside DataFramesMeta.jl macros.

@passmissing is not a "real" Julia macro but rather serves as a "flag" to indicate that the anonymous function created by DataFramesMeta.jl to represent an operation should be wrapped in passmissing from Missings.jl.

@passmissing can only be combined with @byrow or the row-wise versions of macros such as @rtransform and @rselect, etc. If any of the arguments passed to the row-wise anonymous function created by DataFramesMeta.jl with @byrow, the result will automatically be missing.

In the below example, @transform would throw an error without the @passmissing flag.

@passmissing is especially useful for functions which operate on strings, such as parse.

Examples

julia> no_missing(x::Int, y::Int) = x + y;
+  10 │     3      3  c
source
DataFramesMeta.@passmissing — Macro
@passmissing(args...)

Propagate missing values inside DataFramesMeta.jl macros.

@passmissing is not a "real" Julia macro but rather serves as a "flag" to indicate that the anonymous function created by DataFramesMeta.jl to represent an operation should be wrapped in passmissing from Missings.jl.

@passmissing can only be combined with @byrow or the row-wise versions of macros such as @rtransform and @rselect, etc. If any of the arguments passed to the row-wise anonymous function created by DataFramesMeta.jl with @byrow, the result will automatically be missing.

In the below example, @transform would throw an error without the @passmissing flag.

@passmissing is especially useful for functions which operate on strings, such as parse.

Examples

julia> no_missing(x::Int, y::Int) = x + y;
 
 julia> df = DataFrame(a = [1, 2, missing], b = [4, 5, 6])
 3×2 DataFrame
@@ -760,7 +760,7 @@
 ─────┼──────────────────
    1 │ 1              1
    2 │ 2              2
-   3 │ missing  missing
source
DataFramesMeta.@rdistinct! — Macro
rdistinct!(d, args...)

Row-wise version of @distinct!, i.e. all operations use @byrow by default. See @distinct! for details.

Examples

julia> using DataFramesMeta
+   3 │ missing  missing
source
DataFramesMeta.@rdistinct! — Macro
rdistinct!(d, args...)

Row-wise version of @distinct!, i.e. all operations use @byrow by default. See @distinct! for details.

Examples

julia> using DataFramesMeta
 
 julia> df = DataFrame(x = 1:5, y = 5:-1:1)
 5×2 DataFrame
@@ -778,7 +778,7 @@
  Row │ x      y
      │ Int64  Int64
 ─────┼──────────────
-   1 │     1     5
source
DataFramesMeta.@rdistinct — Macro
rdistinct(d, args...)

Row-wise version of @distinct, i.e. all operations use @byrow by default. See @distinct for details.

Examples

julia> using DataFramesMeta
+   1 │     1     5
source
DataFramesMeta.@rdistinct — Macro
rdistinct(d, args...)

Row-wise version of @distinct, i.e. all operations use @byrow by default. See @distinct for details.

Examples

julia> using DataFramesMeta
 
 julia> df = DataFrame(x = 1:5, y = 5:-1:1)
 5×2 DataFrame
@@ -796,7 +796,7 @@
  Row │ x      y
      │ Int64  Int64
 ─────┼──────────────
-   1 │     1     5
source
DataFramesMeta.@rename! — Macro
@rename!(d, args...)

In-place modification of column names.

Arguments

  • d : an AbstractDataFrame
  • args... : expressions of the form :new = :old specifying the change of a column's name

from "old" to "new". The left- and right-hand side of each expression can be passed as symbol arguments, as in :old_col, or strings escaped with $ as in $"new_col". See Details for a description of accepted values.

Returns

  • ::AbstractDataFrame

Inputs to @rename! can come in two formats: a begin ... end block, or as a series of keyword-like arguments. For example, the following are equivalent:

@rename! df begin
+   1 │     1     5
source
DataFramesMeta.@rename! — Macro
@rename!(d, args...)

In-place modification of column names.

Arguments

  • d : an AbstractDataFrame
  • args... : expressions of the form :new = :old specifying the change of a column's name

from "old" to "new". The left- and right-hand side of each expression can be passed as symbol arguments, as in :old_col, or strings escaped with $ as in $"new_col". See Details for a description of accepted values.

Returns

  • ::AbstractDataFrame

Inputs to @rename! can come in two formats: a begin ... end block, or as a series of keyword-like arguments. For example, the following are equivalent:

@rename! df begin
     :new_col = :old_col
 end

and

@rename!(df, :new_col = :old_col)

Details

Both the left- and right-hand side of an expression specifying a column name assignment can be either a Symbol or a Stringescaped with$` For example `:new = ...`, and `$"new" = ...` are both valid ways of assigning a new column name.

This idea can be extended to pass arbitrary right-hand side expressions. For example, the following are equivalent:

@rename!(df, :new = :old1)

and

@rename!(df, :new = old_col1)

Examples

julia> df = DataFrame(old_col1 = rand(5), old_col2 = rand(5),old_col3 = rand(5));
 
@@ -835,7 +835,7 @@
    2 │ 0.861545   0.512254   0.85763
    3 │ 0.263082   0.0267507  0.696494
    4 │ 0.643179   0.299391   0.780125
-   5 │ 0.731267   0.18905    0.767292
source
DataFramesMeta.@rename — Macro
@rename(d, args...)

Change column names.

Arguments

  • d : an AbstractDataFrame
  • args... : expressions of the form :new = :old specifying the change of a column's name

from "old" to "new". The left- and right-hand side of each expression can be passed as symbol arguments, as in :old_col, or strings escaped with $ as in $"new_col". See Details for a description of accepted values.

Returns

  • ::AbstractDataFrame

Inputs to @rename can come in two formats: a begin ... end block, or as a series of keyword-like arguments. For example, the following are equivalent:

@rename df begin
+   5 │ 0.731267   0.18905    0.767292
source
DataFramesMeta.@rename — Macro
@rename(d, args...)

Change column names.

Arguments

  • d : an AbstractDataFrame
  • args... : expressions of the form :new = :old specifying the change of a column's name

from "old" to "new". The left- and right-hand side of each expression can be passed as symbol arguments, as in :old_col, or strings escaped with $ as in $"new_col". See Details for a description of accepted values.

Returns

  • ::AbstractDataFrame

Inputs to @rename can come in two formats: a begin ... end block, or as a series of keyword-like arguments. For example, the following are equivalent:

@rename df begin
     :new_col = :old_col
 end

and

@rename df :new_col = :old_col
 @rename(df, :new_col = :old_col)

Details

Both the left- and right-hand side of an expression specifying a column name assignment can be either a Symbol or an AbstractString (which may contain spaces) escaped with $. For example :new = ..., and $"new" = ... are both valid ways of assigning a new column name.

This idea can be extended to pass arbitrary right-hand side expressions. For example, the following are equivalent:

@rename(df, :new = :old1)

and

@rename(df, :new = old_col1)

The right-hand side can additionally be an Integer, escaped with $, to indicate column position. For example, to rename the 4th column in a data frame to a new name, write @rename df :newname = $.

Examples

julia> df = DataFrame(old_col1 = 1:5, old_col2 = 11:15, old_col3 = 21:25);
@@ -893,7 +893,7 @@
    2 │        2        12        22
    3 │        3        13        23
    4 │        4        14        24
-   5 │        5        15        25
source
DataFramesMeta.@rorderby — Macro
@rorderby(d, args...)

Row-wise version of @orderby, i.e. all operations use @byrow by default. See @orderby for details.

Use this function as an alternative to placing the . to broadcast row-wise operations.

Examples

julia> using DataFramesMeta
+   5 │        5        15        25
source
DataFramesMeta.@rorderby — Macro
@rorderby(d, args...)

Row-wise version of @orderby, i.e. all operations use @byrow by default. See @orderby for details.

Use this function as an alternative to placing the . to broadcast row-wise operations.

Examples

julia> using DataFramesMeta
 
 julia> df = DataFrame(x = [8,8,-8,7,7,-7], y = [-1, 1, -2, 2, -3, 3])
 6×2 DataFrame
@@ -928,7 +928,7 @@
    3 │    -8     -2
    4 │     8     -1
    5 │     8      1
-   6 │    -7      3
source
DataFramesMeta.@rselect! — Macro
@rselect!(x, args...; kwargs...)

Row-wise version of @select!, i.e. all operations use @byrow by default. See @select! for details.

source
DataFramesMeta.@rselect — Macro
@rselect(x, args...; kwargs...)

Row-wise version of @select, i.e. all operations use @byrow by default. See @select for details.

Examples

julia> using DataFramesMeta
+   6 │    -7      3
source
DataFramesMeta.@rselect! — Macro
@rselect!(x, args...; kwargs...)

Row-wise version of @select!, i.e. all operations use @byrow by default. See @select! for details.

source
DataFramesMeta.@rselect — Macro
@rselect(x, args...; kwargs...)

Row-wise version of @select, i.e. all operations use @byrow by default. See @select for details.

Examples

julia> using DataFramesMeta
 
 julia> df = DataFrame(x = 1:5, y = 10:14)
 5×2 DataFrame
@@ -950,7 +950,7 @@
    2 │     2      2
    3 │     3     99
    4 │     4      4
-   5 │     5      5
source
DataFramesMeta.@rsubset! — Macro
@rsubset!(d, i...)

Row-wise version of @subset!, i.e. all operations use @byrow by default. See @subset! for details.

source
DataFramesMeta.@rsubset — Macro
@rsubset(d, i...; kwargs...)

Row-wise version of @subset, i.e. all operations use @byrow by default. See @subset for details.

Use this function as an alternative to placing the . to broadcast row-wise operations.

Examples

julia> using DataFramesMeta
+   5 │     5      5
source
DataFramesMeta.@rsubset! — Macro
@rsubset!(d, i...)

Row-wise version of @subset!, i.e. all operations use @byrow by default. See @subset! for details.

source
DataFramesMeta.@rsubset — Macro
@rsubset(d, i...; kwargs...)

Row-wise version of @subset, i.e. all operations use @byrow by default. See @subset for details.

Use this function as an alternative to placing the . to broadcast row-wise operations.

Examples

julia> using DataFramesMeta
 
 julia> df = DataFrame(A=1:5, B=["apple", "pear", "apple", "orange", "pear"])
 5×2 DataFrame
@@ -978,7 +978,7 @@
  ─────┼───────────────
     1 │     2  pear
     2 │     4  orange
-    3 │     5  pear
source
DataFramesMeta.@rtransform! — Macro
@rtransform!(x, args...; kwargs...)

Row-wise version of @transform!, i.e. all operations use @byrow by default. See @transform! for details.

source
DataFramesMeta.@rtransform — Macro
@rtransform(x, args...; kwargs...)

Row-wise version of @transform, i.e. all operations use @byrow by default. See @transform for details.

Examples

julia> using DataFramesMeta
+    3 │     5  pear
source
DataFramesMeta.@rtransform! — Macro
@rtransform!(x, args...; kwargs...)

Row-wise version of @transform!, i.e. all operations use @byrow by default. See @transform! for details.

source
DataFramesMeta.@rtransform — Macro
@rtransform(x, args...; kwargs...)

Row-wise version of @transform, i.e. all operations use @byrow by default. See @transform for details.

Examples

julia> using DataFramesMeta
 
 julia> df = DataFrame(x = 1:5, y = 11:15)
 5×2 DataFrame
@@ -1000,7 +1000,7 @@
    2 │     2     12    146    -11
    3 │     3     13    172    999
    4 │     4     14    200    -13
-   5 │     5     15    230    -14
source
DataFramesMeta.@select! — Macro
@select!(d, i...; kwargs...)

Mutate d in-place to retain only columns or transformations specified by e and return it. No copies of existing columns are made.

Arguments

  • d : an AbstractDataFrame
  • i : transformations of the form :y = f(:x) specifying

new columns in terms of existing columns or symbols to specify existing columns

  • kwargs : keyword arguments passed to DataFrames.select!

Returns

  • ::DataFrame

Details

Inputs to @select! can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation or selector, or as a series of arguments and keyword-like arguments. For example, the following are equivalent:

@select! uses the syntax @byrow to wrap transformations in the ByRow function wrapper from DataFrames, apply a function row-wise, similar to broadcasting. For example, the call

@select!(df, @byrow :y = :x == 1 ? true : false)

becomes

select!(df, :x => ByRow(x -> x == 1 ? true : false) => :y)

a transformation which cannot be conveniently expressed using broadcasting.

To avoid writing @byrow multiple times when performing multiple transformations by row, @select! allows @byrow at the beginning of a block of select!ations (i.e. @byrow begin... end). All transformations in the block will operate by row.

To select many columns at once use the tools Not, Between, All, and Cols.

  • @select df Not(:a) keeps all columns except for :a
  • @select df Between(:a, :z) keeps all columns between :a and :z, inclusive
  • @select df All() keeps all columns
  • @select df Cols(...) can be used to combine many different selectors, as well as use regular expressions. For example Cols(r"a") selects all columns that start with "a".

Transformations can also use the macro-flag @astable for creating multiple new columns at once and letting transformations share the same name-space. See ? @astable for more details.

In operations, it is also allowed to use AsTable(cols) to work with multiple columns at once, where the columns are grouped together in a NamedTuple. When AsTable(cols) appears in a operation, no other columns may be referenced in the block.

Using AsTable in this way is useful for working with many columns at once programmatically. For example, to compute the row-wise sum of the columns [:a, :b, :c, :d], write

@byrow :c = sum(AsTable([:a, :b, :c, :d]))

This constructs the pairs

AsTable(nms) => ByRow(sum) => :c

AsTable on the right-hand side also allows the use of the special column selectors Not, Between, and regular expressions. For example, to calculate the product of all the columns beginning with the letter "a", write

@byrow :d = prod(AsTable(r"^a"))

@select! accepts the same keyword arguments as DataFrames.select! and can be added in two ways. When inputs are given as multiple arguments, they are added at the end after a semi-colon ;, as in

@select!(gd, :a; ungroup = false)

When inputs are given in "block" format, the last lines may be written @kwarg key = value, which indicates keyword arguments to be passed to select! function.

@select! gd begin
+   5 │     5     15    230    -14
source
DataFramesMeta.@select! — Macro
@select!(d, i...; kwargs...)

Mutate d in-place to retain only columns or transformations specified by e and return it. No copies of existing columns are made.

Arguments

  • d : an AbstractDataFrame
  • i : transformations of the form :y = f(:x) specifying

new columns in terms of existing columns or symbols to specify existing columns

  • kwargs : keyword arguments passed to DataFrames.select!

Returns

  • ::DataFrame

Details

Inputs to @select! can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation or selector, or as a series of arguments and keyword-like arguments. For example, the following are equivalent:

@select! uses the syntax @byrow to wrap transformations in the ByRow function wrapper from DataFrames, apply a function row-wise, similar to broadcasting. For example, the call

@select!(df, @byrow :y = :x == 1 ? true : false)

becomes

select!(df, :x => ByRow(x -> x == 1 ? true : false) => :y)

a transformation which cannot be conveniently expressed using broadcasting.

To avoid writing @byrow multiple times when performing multiple transformations by row, @select! allows @byrow at the beginning of a block of select!ations (i.e. @byrow begin... end). All transformations in the block will operate by row.

To select many columns at once use the tools Not, Between, All, and Cols.

  • @select df Not(:a) keeps all columns except for :a
  • @select df Between(:a, :z) keeps all columns between :a and :z, inclusive
  • @select df All() keeps all columns
  • @select df Cols(...) can be used to combine many different selectors, as well as use regular expressions. For example Cols(r"a") selects all columns that start with "a".

Transformations can also use the macro-flag @astable for creating multiple new columns at once and letting transformations share the same name-space. See ? @astable for more details.

In operations, it is also allowed to use AsTable(cols) to work with multiple columns at once, where the columns are grouped together in a NamedTuple. When AsTable(cols) appears in a operation, no other columns may be referenced in the block.

Using AsTable in this way is useful for working with many columns at once programmatically. For example, to compute the row-wise sum of the columns [:a, :b, :c, :d], write

@byrow :c = sum(AsTable([:a, :b, :c, :d]))

This constructs the pairs

AsTable(nms) => ByRow(sum) => :c

AsTable on the right-hand side also allows the use of the special column selectors Not, Between, and regular expressions. For example, to calculate the product of all the columns beginning with the letter "a", write

@byrow :d = prod(AsTable(r"^a"))

@select! accepts the same keyword arguments as DataFrames.select! and can be added in two ways. When inputs are given as multiple arguments, they are added at the end after a semi-colon ;, as in

@select!(gd, :a; ungroup = false)

When inputs are given in "block" format, the last lines may be written @kwarg key = value, which indicates keyword arguments to be passed to select! function.

@select! gd begin
     :a
     @kwarg ungroup = false
 end

Examples

julia> using DataFrames, DataFramesMeta
@@ -1044,7 +1044,7 @@
    8 │     8      9
 
 julia> df === df2
-true
source
DataFramesMeta.@select — Macro
@select(d, i...; kwargs...)

Select and transform columns.

Arguments

  • d : an AbstractDataFrame or GroupedDataFrame
  • i : transformations of the form :y = f(:x) specifying

new columns in terms of existing columns or symbols to specify existing columns

  • kwargs : keyword arguments passed to DataFrames.select

Returns

  • ::AbstractDataFrame or a GroupedDataFrame

Details

Inputs to @select can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation or selector, or as a series of arguments and keyword-like arguments arguments. For example, the following are equivalent:

@select df begin
+true
source
DataFramesMeta.@select — Macro
@select(d, i...; kwargs...)

Select and transform columns.

Arguments

  • d : an AbstractDataFrame or GroupedDataFrame
  • i : transformations of the form :y = f(:x) specifying

new columns in terms of existing columns or symbols to specify existing columns

  • kwargs : keyword arguments passed to DataFrames.select

Returns

  • ::AbstractDataFrame or a GroupedDataFrame

Details

Inputs to @select can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation or selector, or as a series of arguments and keyword-like arguments arguments. For example, the following are equivalent:

@select df begin
     :x
     :y = :a .+ :b
 end

and

@select(df, :x, :y = :a .+ :b)

@select uses the syntax @byrow to wrap transformations in the ByRow function wrapper from DataFrames, apply a function row-wise, similar to broadcasting. For example, the call

@select(df, @byrow :y = :x == 1 ? true : false)

becomes

select(df, :x => ByRow(x -> x == 1 ? true : false) => :y)

a transformation which cannot be conveniently expressed using broadcasting.

To avoid writing @byrow multiple times when performing multiple transformations by row, @select allows @byrow at the beginning of a block of selections (i.e. @byrow begin... end). All transformations in the block will operate by row.

To select many columns at once use the tools Not, Between, All, and Cols.

  • @select df Not(:a) keeps all columns except for :a
  • @select df Between(:a, :z) keeps all columns between :a and :z, inclusive
  • @select df All() keeps all columns
  • @select df Cols(...) can be used to combine many different selectors, as well as use regular expressions. For example Cols(r"a") selects all columns that start with "a".

Expressions inside Not(...), Between(...) etc. are untouched by DataFramesMeta's parsing. To refer to a variable x which represents a column inside Not, write Not(x), rather than Not($x).

Transformations can also use the macro-flag @astable for creating multiple new columns at once and letting transformations share the same name-space. See ? @astable for more details.

In operations, it is also allowed to use AsTable(cols) to work with multiple columns at once, where the columns are grouped together in a NamedTuple. When AsTable(cols) appears in a operation, no other columns may be referenced in the block.

Using AsTable in this way is useful for working with many columns at once programmatically. For example, to compute the row-wise sum of the columns [:a, :b, :c, :d], write

@byrow :c = sum(AsTable([:a, :b, :c, :d]))

This constructs the pairs

AsTable(nms) => ByRow(sum) => :c

AsTable on the right-hand side also allows the use of the special column selectors Not, Between, and regular expressions. For example, to calculate the product of all the columns beginning with the letter "a", write

@byrow :d = prod(AsTable(r"^a"))

@select accepts the same keyword arguments as DataFrames.select and can be added in two ways. When inputs are given as multiple arguments, they are added at the end after a semi-colon ;, as in

@select(df, :a; copycols = false)

When inputs are given in "block" format, the last lines may be written @kwarg key = value, which indicates keyword arguments to be passed to select function.

@select gd begin
@@ -1083,7 +1083,7 @@
    5 │     5      7
    6 │     6      7
    7 │     7      9
-   8 │     8      9
source
DataFramesMeta.@subset! — Macro
@subset!(d, i...; kwargs...)

Select row subsets in AbstractDataFrames and GroupedDataFrames, mutating the underlying data-frame in-place.

Arguments

  • d : an AbstractDataFrame or GroupedDataFrame
  • i... : expression for selecting rows
  • kwargs : keyword arguments passed to DataFrames.subset!

Details

Multiple i expressions are "and-ed" together.

If given a GroupedDataFrame, @subset! applies transformations by group, and returns a fresh DataFrame containing the rows for which the generated values are all true.

Inputs to @subset! can come in two formats: a begin ... end block, in which case each line is a separate selector, or as multiple arguments. For example the following two statements are equivalent:

@subset! df begin
+   8 │     8      9
source
DataFramesMeta.@subset! — Macro
@subset!(d, i...; kwargs...)

Select row subsets in AbstractDataFrames and GroupedDataFrames, mutating the underlying data-frame in-place.

Arguments

  • d : an AbstractDataFrame or GroupedDataFrame
  • i... : expression for selecting rows
  • kwargs : keyword arguments passed to DataFrames.subset!

Details

Multiple i expressions are "and-ed" together.

If given a GroupedDataFrame, @subset! applies transformations by group, and returns a fresh DataFrame containing the rows for which the generated values are all true.

Inputs to @subset! can come in two formats: a begin ... end block, in which case each line is a separate selector, or as multiple arguments. For example the following two statements are equivalent:

@subset! df begin
     :x .> 1
     :y .< 2
 end

and

@subset!(df, :x .> 1, :y .< 2)
Note

@subset! treats missing values as false when filtering rows. Unlike DataFrames.subset! and other Boolean operations with missing, @subset! will not error on missing values, and will only keep true values.

If an expression provided to @subset! begins with @byrow, operations are applied "by row" along the data frame. To avoid writing @byrow multiple times, @orderby also allows @byrowto be placed at the beginning of a block of operations. For example, the following two statements are equivalent.

@subset! df @byrow begin
@@ -1167,7 +1167,7 @@
  Row │ a       b
      │ Int64?  String?
 ─────┼─────────────────
-   1 │      1  x
source
DataFramesMeta.@subset — Macro
@subset(d, i...; kwargs...)

Select row subsets in AbstractDataFrames and GroupedDataFrames.

Arguments

  • d : an AbstractDataFrame or GroupedDataFrame
  • i... : expression for selecting rows
  • kwargs... : keyword arguments passed to DataFrames.subset

Details

Multiple i expressions are "and-ed" together.

If given a GroupedDataFrame, @subset applies transformations by group, and returns a fresh DataFrame containing the rows for which the generated values are all true.

Inputs to @subset can come in two formats: a begin ... end block, in which case each line is a separate selector, or as multiple arguments. For example the following two statements are equivalent:

@subset df begin
+   1 │      1  x
source
DataFramesMeta.@subset — Macro
@subset(d, i...; kwargs...)

Select row subsets in AbstractDataFrames and GroupedDataFrames.

Arguments

  • d : an AbstractDataFrame or GroupedDataFrame
  • i... : expression for selecting rows
  • kwargs... : keyword arguments passed to DataFrames.subset

Details

Multiple i expressions are "and-ed" together.

If given a GroupedDataFrame, @subset applies transformations by group, and returns a fresh DataFrame containing the rows for which the generated values are all true.

Inputs to @subset can come in two formats: a begin ... end block, in which case each line is a separate selector, or as multiple arguments. For example the following two statements are equivalent:

@subset df begin
     :x .> 1
     :y .< 2
 end

and

@subset(df, :x .> 1, :y .< 2)
Note

@subset treats missing values as false when filtering rows. Unlike DataFrames.subset and other Boolean operations with missing, @subset will not error on missing values, and will only keep true values.

If an expression provided to @subset begins with @byrow, operations are applied "by row" along the data frame. To avoid writing @byrow multiple times, @orderby also allows @byrow to be placed at the beginning of a block of operations. For example, the following two statements are equivalent.

@subset df @byrow begin
@@ -1269,7 +1269,7 @@
      │ Int64?  String?
 ─────┼─────────────────
    1 │      1  x
-   2 │      2  y
source
DataFramesMeta.@transform! — Macro
@transform!(d, i...; kwargs...)

Mutate d inplace to add additional columns or keys based on keyword-like arguments and return it. No copies of existing columns are made.

Arguments

  • d : an AbstractDataFrame, or GroupedDataFrame
  • i... : transformations of the form :y = f(:x) defining new columns or keys
  • kwargs...: keyword arguments passed to DataFrames.transform!

Returns

  • ::DataFrame or a GroupedDataFrame

Details

Inputs to @transform! can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, (:y = f(:x)), or as a series of keyword-like arguments. For example, the following are equivalent:

@transform! df begin
+   2 │      2  y
source
DataFramesMeta.@transform! — Macro
@transform!(d, i...; kwargs...)

Mutate d inplace to add additional columns or keys based on keyword-like arguments and return it. No copies of existing columns are made.

Arguments

  • d : an AbstractDataFrame, or GroupedDataFrame
  • i... : transformations of the form :y = f(:x) defining new columns or keys
  • kwargs...: keyword arguments passed to DataFrames.transform!

Returns

  • ::DataFrame or a GroupedDataFrame

Details

Inputs to @transform! can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, (:y = f(:x)), or as a series of keyword-like arguments. For example, the following are equivalent:

@transform! df begin
     :a = :x
     :b = :y
 end

and

@transform!(df, :a = :x, :b = :y)

@transform! uses the syntax @byrow to wrap transform!ations in the ByRow function wrapper from DataFrames, apply a function row-wise, similar to broadcasting. For example, the call

@transform!(df, @byrow :y = :x == 1 ? true : false)

becomes

transform!(df, :x => ByRow(x -> x == 1 ? true : false) => :y)

a transformation which cannot be conveniently expressed using broadcasting.

To avoid writing @byrow multiple times when performing multiple transform!ations by row, @transform! allows @byrow at the beginning of a block of transform!ations (i.e. @byrow begin... end). All transform!ations in the block will operate by row.

Transformations can also use the macro-flag @astable for creating multiple new columns at once and letting transformations share the same name-space. See ? @astable for more details.

In operations, it is also allowed to use AsTable(cols) to work with multiple columns at once, where the columns are grouped together in a NamedTuple. When AsTable(cols) appears in a operation, no other columns may be referenced in the block.

Using AsTable in this way is useful for working with many columns at once programmatically. For example, to compute the row-wise sum of the columns [:a, :b, :c, :d], write

@byrow :c = sum(AsTable([:a, :b, :c, :d]))

This constructs the pairs

AsTable(nms) => ByRow(sum) => :c

AsTable on the right-hand side also allows the use of the special column selectors Not, Between, and regular expressions. For example, to calculate the product of all the columns beginning with the letter "a", write

@byrow :d = prod(AsTable(r"^a"))

@transform! accepts the same keyword arguments as DataFrames.transform! and can be added in two ways. When inputs are given as multiple arguments, they are added at the end after a semi-colon ;, as in

@transform!(gd, :x = :a .- 1; ungroup = false)

When inputs are given in "block" format, the last lines may be written @kwarg key = value, which indicates keyword arguments to be passed to transform! function.

@transform! gd begin
@@ -1289,7 +1289,7 @@
    3 │     3      2      6      5
 
 julia> df === df2
-true
source
DataFramesMeta.@transform — Macro
@transform(d, i...; kwargs...)

Add additional columns or keys based on keyword-like arguments.

Arguments

  • d: an AbstractDataFrame, or GroupedDataFrame
  • i...: transformations defining new columns or keys, of the form :y = f(:x)
  • kwargs...: keyword arguments passed to DataFrames.transform

Returns

  • ::AbstractDataFrame or ::GroupedDataFrame

Details

Inputs to @transform can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, (:y = f(:x)), or as a series of keyword-like arguments. For example, the following are equivalent:

@transform df begin
+true
source
DataFramesMeta.@transform — Macro
@transform(d, i...; kwargs...)

Add additional columns or keys based on keyword-like arguments.

Arguments

  • d: an AbstractDataFrame, or GroupedDataFrame
  • i...: transformations defining new columns or keys, of the form :y = f(:x)
  • kwargs...: keyword arguments passed to DataFrames.transform

Returns

  • ::AbstractDataFrame or ::GroupedDataFrame

Details

Inputs to @transform can come in two formats: a begin ... end block, in which case each line in the block is a separate transformation, (:y = f(:x)), or as a series of keyword-like arguments. For example, the following are equivalent:

@transform df begin
     :a = :x
     :b = :y
 end

and

@transform(df, :a = :x, :b = :y)

@transform uses the syntax @byrow to wrap transformations in the ByRow function wrapper from DataFrames, apply a function row-wise, similar to broadcasting. For example, the call

@transform(df, @byrow :y = :x == 1 ? true : false)

becomes

transform(df, :x => ByRow(x -> x == 1 ? true : false) => :y)

a transformation which cannot be conveniently expressed using broadcasting.

To avoid writing @byrow multiple times when performing multiple transformations by row, @transform allows @byrow at the beginning of a block of transformations (i.e. @byrow begin... end). All transformations in the block will operate by row.

Transformations can also use the macro-flag @astable for creating multiple new columns at once and letting transformations share the same name-space. See ? @astable for more details.

In operations, it is also allowed to use AsTable(cols) to work with multiple columns at once, where the columns are grouped together in a NamedTuple. When AsTable(cols) appears in a operation, no other columns may be referenced in the block.

Using AsTable in this way is useful for working with many columns at once programmatically. For example, to compute the row-wise sum of the columns [:a, :b, :c, :d], write

@byrow :c = sum(AsTable([:a, :b, :c, :d]))

This constructs the pairs

AsTable(nms) => ByRow(sum) => :c

AsTable on the right-hand side also allows the use of the special column selectors Not, Between, and regular expressions. For example, to calculate the product of all the columns beginning with the letter "a", write

@byrow :d = prod(AsTable(r"^a"))

@transform accepts the same keyword arguments as DataFrames.transform! and can be added in two ways. When inputs are given as multiple arguments, they are added at the end after a semi-colon ;, as in

@transform(gd, :x = :a .- 1; ungroup = false)

When inputs are given in "block" format, the last lines may be written @kwarg key = value, which indicates keyword arguments to be passed to transform! function.

@transform gd begin
@@ -1330,7 +1330,7 @@
 ─────┼────────────────────────────
    1 │     1      2      2    100
    2 │     2      1      2    200
-   3 │     3      2      6    200
source
DataFramesMeta.@where — Macro
@where(x, args...)

Deprecated version of @subset, see ?@subset for details.

source
DataFramesMeta.@with — Macro
@with(d, expr)

@with allows DataFrame columns keys to be referenced as symbols.

Arguments

  • d : an AbstractDataFrame type
  • expr : the expression to evaluate in d

Details

@with works by parsing the expression body for all columns indicated by symbols (e.g. :colA). Then, a function is created that wraps the body and passes the columns as function arguments. This function is then called. Operations are efficient because:

  • A pseudo-anonymous function is defined, so types are stable.
  • Columns are passed as references, eliminating DataFrame indexing.

The following

@with(d, :a .+ :b .+ 1)

becomes

tempfun(a, b) = a .+ b .+ 1
+   3 │     3      2      6    200
source
DataFramesMeta.@where — Macro
@where(x, args...)

Deprecated version of @subset, see ?@subset for details.

source
DataFramesMeta.@with — Macro
@with(d, expr)

@with allows DataFrame columns keys to be referenced as symbols.

Arguments

  • d : an AbstractDataFrame type
  • expr : the expression to evaluate in d

Details

@with works by parsing the expression body for all columns indicated by symbols (e.g. :colA). Then, a function is created that wraps the body and passes the columns as function arguments. This function is then called. Operations are efficient because:

  • A pseudo-anonymous function is defined, so types are stable.
  • Columns are passed as references, eliminating DataFrame indexing.

The following

@with(d, :a .+ :b .+ 1)

becomes

tempfun(a, b) = a .+ b .+ 1
 tempfun(d[!, :a], d[!, :b])

If an expression is wrapped in ^(expr), expr gets passed through untouched. If an expression is wrapped in $(expr), the column is referenced by the variable expr rather than a symbol.

If the expression provide to @with begins with @byrow, the function created by the @with block is broadcasted along the columns of the data frame.

Examples

julia> using DataFramesMeta
 
 julia> y = 3;
@@ -1378,4 +1378,4 @@
  2
  2
  6
-
Note

@with creates a function, so the scope within @with is a local scope. Variables in the parent can be read. Writing to variables in the parent scope differs depending on the type of scope of the parent. If the parent scope is a global scope, then a variable cannot be assigned without using the global keyword. If the parent scope is a local scope (inside a function or let block for example), the global keyword is not needed to assign to that parent scope.

Note

Using AsTable inside @with block is currently not supported.

source
+
Note

@with creates a function, so the scope within @with is a local scope. Variables in the parent can be read. Writing to variables in the parent scope differs depending on the type of scope of the parent. If the parent scope is a global scope, then a variable cannot be assigned without using the global keyword. If the parent scope is a local scope (inside a function or let block for example), the global keyword is not needed to assign to that parent scope.

Note

Using AsTable inside @with block is currently not supported.

source diff --git a/dev/dplyr/index.html b/dev/dplyr/index.html index 28a972e..b6fdeb3 100644 --- a/dev/dplyr/index.html +++ b/dev/dplyr/index.html @@ -515,4 +515,4 @@ 81 │ Genet Genetta carni Carnivora miss ⋯ 82 │ Arctic fox Vulpes carni Carnivora miss 83 │ Red fox Vulpes carni Carnivora miss - 8 columns and 68 rows omitted

This short tutorial only touches on the wide array of features in Julia, DataFrames.jl, and DataFramesMeta.jl. Read the full documentation for more information.

+ 8 columns and 68 rows omitted

This short tutorial only touches on the wide array of features in Julia, DataFrames.jl, and DataFramesMeta.jl. Read the full documentation for more information.

diff --git a/dev/index.html b/dev/index.html index 821e912..efed3e5 100644 --- a/dev/index.html +++ b/dev/index.html @@ -374,4 +374,4 @@ Column: age ─────────── Label: Age (years) - + diff --git a/dev/search/index.html b/dev/search/index.html index 6fc4065..21b9b5c 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · DataFramesMeta Documentation

Loading search...

    +Search · DataFramesMeta Documentation

    Loading search...