fixes n slice_min/max bug (#110)

* fixes `n` slice_min/max bug

* adds `@head`

* Clean up documentation in prep for release, bump version to v0.16.2.

* Fix doctest.

---------

Co-authored-by: Karandeep Singh <[email protected]>

Author: drizk1

NEWS.md

@@ -1,5 +1,9 @@
 # TidierData.jl updates
 
+## v0.16.2 - 2024-08-05
+- Bugfix: `@slice_min` and `@slice_max` respect the `n` argument
+- Adds `@head`
+
 ## v0.16.1 - 2024-06-09
 - Adds support for tuples and vectors as arguments to select multiple columns. Prefixing tuples/vectors with a `-` or `!` will exclude the selected columns.
 - The `:` selector from Julia is now available and equivalent to `everything()`

Project.toml

@@ -1,7 +1,7 @@
 name = "TidierData"
 uuid = "fe2206b3-d496-4ee9-a338-6a095c4ece80"
 authors = ["Karandeep Singh"]
-version = "0.16.1"
+version = "0.16.2"
 
 [deps]
 Chain = "8be319e6-bccf-4806-a6f7-6fae938471bc"

README.md

@@ -67,7 +67,7 @@ To support R-style programming, TidierData.jl is implemented using macros.
 
 TidierData.jl currently supports the following top-level macros:
 
-- `@glimpse()`
+- `@glimpse()` and `@head()`
 - `@select()` and `@distinct()`
 - `@rename()` and `@rename_with()`
 - `@mutate()` and `@transmute()` 

docs/src/index.md

@@ -84,7 +84,7 @@ TidierData.jl currently supports the following top-level macros:
 
 ```@raw html
 !!! example "Top-level macros:"
-    - `@glimpse()`
+    - `@glimpse()` and `@head()`
     - `@select()` and `@distinct()`
     - `@rename()` and `@rename_with()`
     - `@mutate()` and `@transmute()` 

src/TidierData.jl

@@ -21,7 +21,7 @@ export TidierData_set, across, desc, n, row_number, everything, starts_with, end
       @group_by, @ungroup, @slice, @arrange, @distinct, @pull, @left_join, @right_join, @inner_join, @full_join, @anti_join, @semi_join,
       @pivot_wider, @pivot_longer, @bind_rows, @bind_cols, @clean_names, @count, @tally, @drop_missing, @glimpse, @separate,
       @unite, @summary, @fill_missing, @slice_sample, @slice_min, @slice_max, @slice_head, @slice_tail, @rename_with, @separate_rows,
-      @unnest_longer, @unnest_wider, @nest, @relocate
+      @unnest_longer, @unnest_wider, @nest, @relocate, @head
 
 # Package global variables
 const code = Ref{Bool}(false) # output DataFrames.jl code?
@@ -688,4 +688,24 @@ macro rename_with(df, fn, exprs...)
   return df_expr
 end
 
+"""
+$docstring_head
+"""
+macro head(df, exprs=6)
+  return quote
+      local df_input = $(esc(df))
+      local n = $(esc(exprs))
+      
+      if df_input isa GroupedDataFrame
+          grouped_result = combine(df_input) do sdf
+              first(sdf, n)
+          end
+          groupby(grouped_result, df_input.cols)
+      else
+          first(copy(df_input), n)
+      end
+  end
+end
+
+
 end

src/docstrings.jl

@@ -2834,14 +2834,15 @@ julia> @chain df begin
    1 │      5.0       7.0       5.0
 
 julia> @chain df begin
-         @slice_max(b, with_ties = false, n = 2)
+         @slice_max(b, n = 3)
        end 
-2×3 DataFrame
+3×3 DataFrame
  Row │ a         b         c        
      │ Float64?  Float64?  Float64? 
 ─────┼──────────────────────────────
    1 │      5.0       7.0       5.0
    2 │      6.0       7.0       6.0
+   3 │      1.0       6.0       1.0
    
 julia> @chain df begin
          @slice_max(b, prop = 0.5, missing_rm = true)
@@ -2897,15 +2898,15 @@ julia> @chain df begin
    1 │  missing       0.3       0.2
 
 julia> @chain df begin
-         @slice_min(b, with_ties = true, n = 1)
-       end 
-2×3 DataFrame
- Row │ a         b         c         
-     │ Float64?  Float64?  Float64?  
-─────┼───────────────────────────────
-   1 │  missing       0.3        0.2
-   2 │  missing       0.3  missing   
-  
+         @slice_min(b, n = 3)
+       end
+3×3 DataFrame
+ Row │ a          b         c         
+     │ Float64?   Float64?  Float64?  
+─────┼────────────────────────────────
+   1 │ missing         0.3        0.2
+   2 │ missing         0.3  missing   
+   3 │       0.2       2.0        0.2  
    
 julia> @chain df begin
          @slice_min(b, prop = 0.5, missing_rm = true)
@@ -2950,7 +2951,7 @@ julia> @chain df begin
    3 │ missing    missing         0.2
 
 julia> @chain df begin
-         @slice_head(prop = .25)
+         @slice_head(prop = 0.25)
        end 
 2×3 DataFrame
  Row │ a          b         c        
@@ -2991,7 +2992,7 @@ julia> @chain df begin
    3 │       6.0       7.0        6.0
 
 julia> @chain df begin
-         @slice_tail(prop = .25)
+         @slice_tail(prop = 0.25)
        end 
 2×3 DataFrame
  Row │ a         b         c        
@@ -3461,3 +3462,72 @@ julia> @relocate(df, B:C) # bring columns to the front
    5 │    10  E           5  C         5  E
 ```
 """
+
+const docstring_head =
+"""
+       @head(df, value)
+Shows the first n rows of the the data frame or of each group in a grouped data frame. 
+
+# Arguments
+- `df`: The data frame.
+- `value`: number of rows to be returned. Defaults to 6 if left blank.
+
+# Examples
+```
+julia> df = DataFrame(a = vcat(repeat(["a"], inner = 4),
+                                  repeat(["b"], inner = 4)),
+                             b = 1:8)
+8×2 DataFrame
+ Row │ a       b     
+     │ String  Int64 
+─────┼───────────────
+   1 │ a           1
+   2 │ a           2
+   3 │ a           3
+   4 │ a           4
+   5 │ b           5
+   6 │ b           6
+   7 │ b           7
+   8 │ b           8
+   
+julia> @head(df, 3)
+3×2 DataFrame
+ Row │ a        b     
+     │ String?  Int64 
+─────┼────────────────
+   1 │ a            1
+   2 │ a            2
+   3 │ a            3
+
+julia> @head(df)
+6×2 DataFrame
+ Row │ a       b     
+     │ String  Int64 
+─────┼───────────────
+   1 │ a           1
+   2 │ a           2
+   3 │ a           3
+   4 │ a           4
+   5 │ b           5
+   6 │ b           6
+
+julia> @chain df begin
+         @group_by a
+         @head 2
+       end
+GroupedDataFrame with 2 groups based on key: a
+First Group (2 rows): a = "a"
+ Row │ a       b     
+     │ String  Int64 
+─────┼───────────────
+   1 │ a           1
+   2 │ a           2
+⋮
+Last Group (2 rows): a = "b"
+ Row │ a       b     
+     │ String  Int64 
+─────┼───────────────
+   1 │ b           5
+   2 │ b           6
+```
+"""