From 916b287184e5049de42734403cc5d1c6be693bd1 Mon Sep 17 00:00:00 2001
From: Nathan Boyer <65452054+nathanrboyer@users.noreply.github.com>
Date: Mon, 1 Jun 2026 09:09:20 -0400
Subject: [PATCH 1/3] Add Usage and Alternatives sections to README

---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.md b/README.md
index e9aee0c5..7f426405 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,41 @@ or via the `Pkg` REPL mode (enter by typing `]` at the REPL console)
 ] add DataFramesMeta
 ```
 
+# Usage
+
+Instead of using DataFrames.jl [manipulation functions](https://dataframes.juliadata.org/stable/man/basics/#Manipulation-Functions) directly,
+which use operation pairs to define data frame manipulations,
+DataFramesMeta.jl offers macro alternatives to each manipulation function,
+which convert a more readable syntax into the appropriate DataFrames.jl function calls.
+This syntax simplification is demonstrated with two simple examples below.
+
+Define a data frame.
+
+```julia
+df = DataFrame(a = [1, 2], b = [3, 4]);
+```
+
+Add columns `a` and `b` together and store the result in a new column `c`.
+
+```julia
+# With DataFrames
+transform(df, [:a, :b] => ((x, y) -> x + y) => :c)
+
+# With DataFramesMeta
+@transform(df, :c = :a + :b)
+```
+
+Show only the data frame rows where column `a` is equal to `2`.
+(DataFramesMeta.jl offers rowwise 'r' versions of each manipulation macro as well for convenience.)
+
+```julia
+# With DataFrames
+subset(df, :a => ByRow(==(2)))
+
+# With DataFramesMeta
+@rsubset(df, :a == 2)
+```
+
 # Documentation
 
 * [Stable](https://JuliaData.github.io/DataFramesMeta.jl/stable)
@@ -37,3 +72,7 @@ Pull requests are welcome. Pull requests should include updated tests. If
 functionality is changed, docstrings should be added or updated. Generally,
 follow the guidelines in
 [DataFrames](https://github.com/JuliaData/DataFrames.jl/blob/master/CONTRIBUTING.md).
+
+# Alternatives
+
+Other high-level data frame manipulation packages are described briefly [here](https://dataframes.juliadata.org/stable/man/querying_frameworks/).

From 37c08b8867d7909a655de13ee3e2720a872212e2 Mon Sep 17 00:00:00 2001
From: Nathan Boyer <65452054+nathanrboyer@users.noreply.github.com>
Date: Mon, 1 Jun 2026 09:16:00 -0400
Subject: [PATCH 2/3] Add `using DataFramesMeta` to example

---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index 7f426405..a25d51d1 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,8 @@ This syntax simplification is demonstrated with two simple examples below.
 Define a data frame.
 
 ```julia
+# Importing DataFramesMeta also implicitly imports DataFrames
+using DataFramesMeta
 df = DataFrame(a = [1, 2], b = [3, 4]);
 ```
 

From 1efb0068ac66d8db50ab7988c30d788d4d46dda2 Mon Sep 17 00:00:00 2001
From: Nathan Boyer <65452054+nathanrboyer@users.noreply.github.com>
Date: Mon, 1 Jun 2026 09:20:34 -0400
Subject: [PATCH 3/3] Remove unneeded `;`

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a25d51d1..6a21cc86 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ Define a data frame.
 ```julia
 # Importing DataFramesMeta also implicitly imports DataFrames
 using DataFramesMeta
-df = DataFrame(a = [1, 2], b = [3, 4]);
+df = DataFrame(a = [1, 2], b = [3, 4])
 ```
 
 Add columns `a` and `b` together and store the result in a new column `c`.