update docstring

Author: sl-solution

src/dataset/combine.jl

@@ -522,6 +522,73 @@ function _combine_f_barrier_tuple(fromds, newds, msfirst, mssecond, mslast, newd
 
 end
 
+"""
+    combine(ds::AbstractDataset, args...; dropgroupcols = false, threads = true)
+
+Create a new data set while the `args` aggregations has been applied on passed columns. The `args` argument must be in the form of `cols=>fun=>newname`, where `cols` refers to columns in the passed data set. `fun` assumes a single column as its input, thus, multiple columns will be broadcasted, i.e. `cols=>fun` will be tranlated as `col1=>fun`, `col2=>fun`, ..., and `col=>funs` will be translated as `col=>fun1`, `col=>fun2`, .... The `byrow` function can be passed as `fun`, however, its input must be referring to columns which already an operation has been done on them.
+
+For using a multivate function the columns must be passed as tuple of column names or column indices.
+
+For grouped data set the operations are done on each group of observations.
+
+# Examples
+
+```jldoctest
+julia> ds = Dataset(g = [1,2,1,2,1,2], x = 1:6)
+6×2 Dataset
+ Row │ g         x
+     │ identity  identity
+     │ Int64?    Int64?
+─────┼────────────────────
+   1 │        1         1
+   2 │        2         2
+   3 │        1         3
+   4 │        2         4
+   5 │        1         5
+   6 │        2         6
+
+julia> combine(groupby(ds, :g), :x=>[sum, mean])
+2×3 Dataset
+ Row │ g         sum_x     mean_x
+     │ identity  identity  identity
+     │ Int64?    Int64?    Float64?
+─────┼──────────────────────────────
+   1 │        1         9       3.0
+   2 │        2        12       4.0
+
+julia> combine(gatherby(ds, :g), :x => [maximum, minimum], 2:3 => byrow(-) => :range)
+2×4 Dataset
+ Row │ g         maximum_x  minimum_x  range
+     │ identity  identity   identity   identity
+     │ Int64?    Int64?     Int64?     Int64?
+─────┼──────────────────────────────────────────
+   1 │        1          5          1         4
+   2 │        2          6          2         4
+
+julia> ds = Dataset(g = [1,2,1,2,1,2], x = 1:6, y = 6:-1:1)
+6×3 Dataset
+ Row │ g         x         y
+     │ identity  identity  identity
+     │ Int64?    Int64?    Int64?
+─────┼──────────────────────────────
+   1 │        1         1         6
+   2 │        2         2         5
+   3 │        1         3         4
+   4 │        2         4         3
+   5 │        1         5         2
+   6 │        2         6         1
+
+julia> combine(groupby(ds,1), (:x, :y)=>(x1,x2)->maximum(x1)-minimum(x2))
+2×2 Dataset
+ Row │ g         function_x_y
+     │ identity  identity
+     │ Int64?    Int64?
+─────┼────────────────────────
+   1 │        1             3
+   2 │        2             5
+
+```
+"""
 function combine(ds::Dataset, @nospecialize(args...); dropgroupcols = false, threads = true)
     !isgrouped(ds) &&  return combine_ds(ds, args...)#throw(ArgumentError("`combine` is only for grouped data sets, use `modify` instead"))
     idx_cpy::Index = Index(Dict{Symbol, Int}(), Symbol[], Dict{Int, Function}())

src/dataset/modify.jl

@@ -281,9 +281,121 @@ function normalize_modify_multiple!(outidx::Index, idx, @nospecialize(args...))
     res
 end
 
+"""
+    modify(...)
+
+A variant of `modify!` which modifies a copy of the passed data set.
+
+See [`modify!`](@ref)
+"""
 modify(origninal_ds::AbstractDataset, @nospecialize(args...); threads::Bool = true) = modify!(copy(origninal_ds), args...; threads = threads)
 
 modify!(ds::Dataset; threads::Bool = true) = parent(ds)
+
+"""
+    modify!(ds::AbstractDataset, args...; [threads = true])
+
+Modify columns of a data set. The `args` arguments must be in the form of `cols => fun => newnames`. The `fun` function will be called on passed `cols`, with the excpetion of two special functions: `byrow` and `splitter`. `fun` assumes a single column as its input, thus passing multiple columns will be broadcasted, i.e. `cols => fun` will be translated to `col1=>fun`, `col2=>fun`, .... When `newname` is not provided `modify!` modifies the passed column.
+
+When a grouped data set is passed to `modify!`, the operation is done on each group of observations.
+
+each `args` can be constructed based on columns in the original data set or the columns which have been created before it.
+
+# Special functions
+
+`byrow` and `splitter` are two special functions which can be passed as `fun`.
+
+`byrow` can accept multiple columns as input and does a given operation on each row of the data set. When a single column is passed to `byrow`, `modify!` modifies the passed column, however, when multiple columns are passed, `byrow` applies the row-wise operation on them and creates a new column.
+
+`splitter` splits a column of tuples to multiple columns. When `splitter` is set as `fun` the `newnames` must be given.
+
+# Using multivariate functions
+
+To pass multiple columns to a `fun` function which operates on multiple inputs, the columns must be passed as tuple of column names, or column indices.
+
+See [`modify`](@ref)
+
+# Examples
+
+```jldoctest
+julia> ds = Dataset(x1 = 1:5, x2 = [-2, -1, missing, 1, 2],
+                    x3 = [0.0, 0.1, 0.2, missing, 0.4])
+5×3 Dataset
+ Row │ x1        x2        x3
+     │ identity  identity  identity
+     │ Int64?    Int64?    Float64?
+─────┼──────────────────────────────
+   1 │        1        -2       0.0
+   2 │        2        -1       0.1
+   3 │        3   missing       0.2
+   4 │        4         1   missing
+   5 │        5         2       0.4
+
+julia> modify!(ds, 2:3 => sum)
+5×3 Dataset
+ Row │ x1        x2        x3
+     │ identity  identity  identity
+     │ Int64?    Int64?    Float64?
+─────┼──────────────────────────────
+   1 │        1         0       0.7
+   2 │        2         0       0.7
+   3 │        3         0       0.7
+   4 │        4         0       0.7
+   5 │        5         0       0.7
+
+julia> modify!(ds, :x1 => x -> x .- mean(x))
+5×3 Dataset
+ Row │ x1        x2        x3
+     │ identity  identity  identity
+     │ Float64?  Int64?    Float64?
+─────┼──────────────────────────────
+   1 │     -2.0         0       0.7
+   2 │     -1.0         0       0.7
+   3 │      0.0         0       0.7
+   4 │      1.0         0       0.7
+   5 │      2.0         0       0.7
+
+julia> body = Dataset(weight = [78.5, 59, 80], height = [160, 171, 183])
+3×2 Dataset
+ Row │ weight    height
+     │ identity  identity
+     │ Float64?  Int64?
+─────┼────────────────────
+   1 │     78.5       160
+   2 │     59.0       171
+   3 │     80.0       183
+
+julia> modify!(body, :height => byrow(x -> (x/100)^2) => :BMI, [1, 3] => byrow(/) => :BMI)
+3×3 Dataset
+ Row │ weight    height    BMI
+     │ identity  identity  identity
+     │ Float64?  Int64?    Float64?
+─────┼──────────────────────────────
+   1 │     78.5       160   30.6641
+   2 │     59.0       171   20.1771
+   3 │     80.0       183   23.8884
+
+julia> body = Dataset(weight = [78.5, 59, 80], height = [160, 171, 183])
+3×2 Dataset
+ Row │ weight    height
+     │ identity  identity
+     │ Float64?  Int64?
+─────┼────────────────────
+   1 │     78.5       160
+   2 │     59.0       171
+   3 │     80.0       183
+
+julia> modify!(body, (:weight, :height)=> cor)
+3×3 Dataset
+ Row │ weight    height    cor_weight_height
+     │ identity  identity  identity
+     │ Float64?  Int64?    Float64?
+─────┼───────────────────────────────────────
+   1 │     78.5       160          0.0890411
+   2 │     59.0       171          0.0890411
+   3 │     80.0       183          0.0890411
+```
+"""
 function modify!(ds::AbstractDataset, @nospecialize(args...); threads::Bool = true)
     if ds isa SubDataset
 		idx_cpy = copy(index(parent(ds)))