dataframe-toolkit 0.4.1__py3-none-any.whl

dataframe_toolkit-0.4.1.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.3
+Name: dataframe-toolkit
+Version: 0.4.1
+Summary: A command-line toolkit for DataFrame analysis and manipulation
+Keywords: dataframe,statistics,data analysis,CLI,TSV,pandas
+Author: Gunnar Pálsson
+Author-email: Gunnar Pálsson <hemingur@gmail.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: pandas>=2.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyarrow>=12.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: duckdb>=0.8
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.12
+Requires-Dist: tqdm>=4.65
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/hemingur/dataframe-toolkit
+Project-URL: Repository, https://github.com/hemingur/dataframe-toolkit
+Description-Content-Type: text/markdown
+
+# dftk — DataFrame analysis and manipulation toolkit
+
+`dftk` is a command-line toolkit for exploratory data analysis on TSV files.
+Each subcommand reads tabular data, performs one operation, and writes TSV to
+stdout, making it easy to chain commands in pipelines.
+
+`dftk` was developed during computational genomics research as a fast,
+composable alternative to writing one-off pandas scripts. It is designed
+for analysts who live in the terminal and want a consistent, pipeable toolkit
+for the full data analysis pipeline — from initial exploration through
+statistical modelling and publication-quality figures.
+
+## Installation
+
+```bash
+uv tool install dataframe-toolkit
+dftk --help
+```
+
+Or with `pip`:
+
+```bash
+pip install dataframe-toolkit
+```
+
+To install the latest `main` branch directly from GitHub:
+
+```bash
+uv tool install git+https://github.com/hemingur/dataframe-toolkit.git
+```
+
+To install from a local clone:
+
+```bash
+git clone https://github.com/hemingur/dataframe-toolkit.git
+cd dataframe-toolkit
+uv tool install .
+```
+
+## Quick example
+
+```bash
+dftk stat data.tsv -c height weight -g sex
+dftk stat data.tsv -c value -g group -o \
+  | dftk pivot -i group -v value_mean -o \
+  | dftk print
+```
+
+## Subcommands
+
+### Data transformation
+
+| Command   | Description                                                                          |
+|-----------|--------------------------------------------------------------------------------------|
+| `eval`    | Add or modify columns: eval expressions, string/path functions, statistical ops      |
+| `query`   | Filter rows with pandas query expressions or SQL (`--sql` via DuckDB)                |
+| `merge`   | Join two tables on key columns (inner/left/right/outer)                              |
+| `concat`  | Concatenate two or more tables row-wise                                              |
+| `melt`    | Reshape wide-to-long (`pd.melt`)                                                     |
+| `pivot`   | Reshape long-to-wide with per-cell aggregation                                       |
+| `func`    | Column transforms: cumsum, group mean/sum/min/max/count/median/std, rank, qcut:N     |
+| `scale`   | Normalise: z-score, min-shift, sum/max/mean scaling, Blom rank, regression residuals |
+| `interp`  | Interpolate values from a reference curve into a table (1-D lookup)                  |
+| `binx`    | Assign bin indices to a column based on explicit or generated edges                  |
+
+### Statistics
+
+| Command    | Description                                                                                         |
+|------------|-----------------------------------------------------------------------------------------------------|
+| `stat`     | Descriptive statistics (count/mean/std/CI/SEM/skew/kurtosis) with grouping and bootstrap            |
+| `wstat`    | Weighted descriptive statistics (wmean, wstd, weighted quantile CI)                                 |
+| `fit`      | OLS/robust/weighted regression via R-style formulas; tidy table, `--summary`, `--anova`             |
+| `test`     | P-values between column pairs: t-test, Mann-Whitney, Wilcoxon, KS, correlations, bootstrap; groups  |
+| `corr`     | Pairwise column correlations (Pearson/Spearman/Kendall) with optional BCa bootstrap CI              |
+| `describe` | Quick column-level summary (dtype, n, n_unique, n_null, sample values)                              |
+| `randvar`  | Sample from a distribution and append as a new column (norm, alpha, beta, …)                        |
+
+### Plots
+
+All plot commands write a PNG/PDF when `-f FILE` is given, or display
+interactively otherwise. They support `--groupcol` for colour grouping,
+`--subgraphcol` for subplot grids, and figure/font presets for
+publication-quality output.
+
+| Command | Description                                                                                     |
+|---------|-------------------------------------------------------------------------------------------------|
+| `scat`  | Scatter plot; optional OLS/robust fit overlay, bubble size (`--sizecol`), colour (`--colorcol`) |
+| `line`  | Line plot; optional error bars (`--yerr`) or CI bands (`--yci lo,hi`) and fit overlay           |
+| `hist`  | Histogram or KDE (`--kde`); normalisation, cumulative mode, mean±σ annotation (`--stats`)       |
+
+### Utilities
+
+| Command    | Description                                                              |
+|------------|--------------------------------------------------------------------------|
+| `dataset`  | Load a curated example dataset from seaborn, statsmodels, or pydataset   |
+| `sample`   | Random row sampling (with or without replacement, by count or fraction)   |
+| `split`    | Split a dataframe into one file per group                                 |
+| `annotate` | Read and write provenance metadata (genome, source, …) in parquet files  |
+| `print`    | Read any dftk input (TSV, stdin, `...` parquet pipe) and write TSV     |
+| `clean`    | Remove leftover temp parquet pipe files from interrupted pipelines       |
+| `help`     | List all subcommands or show full help for one: `dftk help stat`       |
+
+## Common patterns
+
+### Chaining commands
+
+```bash
+# z-score within group, then fit a model
+dftk scale data.tsv -c expr -g condition -o \
+  | dftk fit - -f "expr_z ~ time + batch" -g condition
+```
+
+### Group summary then plot
+
+```bash
+dftk stat results.tsv -c value -g group -o \
+  | dftk line - -x group -y value_mean --yerr value_sem -f fig.png
+```
+
+### Wide-to-long then plot overlaid histograms
+
+```bash
+dftk melt data.tsv -i sample -d gene -v expression \
+  | dftk hist - -x expression -g gene -k -f dist.png
+```
+
+### Interpolation (standard curve lookup)
+
+```bash
+dftk interp samples.tsv --ref stdcurve.tsv \
+    -x fluorescence -v concentration -d conc_ng_ul
+```
+
+### Bootstrap confidence intervals
+
+```bash
+dftk stat data.tsv -c value -g group --bootstrap 1000 --randomseed 42 -o \
+  | dftk pivot -i group -v value_mean -f mean -o \
+  | dftk stat - -c group_A group_B
+```
+
+## Input/output
+
+All commands accept:
+
+- A TSV filename as a positional argument
+- `-` to read TSV from stdin
+- `...` to receive a parquet path from stdin (written by a previous `-o` command)
+- A `.parquet` filename to read a named parquet file directly
+
+Standard output options (available on all tabular commands):
+
+- `-o` / `--output` — write a temp parquet for the next piped command instead of TSV to stdout
+- `--select col1 col2 …` — keep only these columns
+- `--drop col1 col2 …` — remove these columns
+- `--round N` — round numeric output
+- `--postquery EXPR` — filter output rows after processing
+- `--meta KEY=VALUE` — embed provenance metadata in parquet output (repeatable)
+
+### Provenance annotations
+
+Metadata embedded with `--meta` is stored in the parquet file schema and propagates
+automatically through the pipe: every subsequent `-o` write re-embeds it alongside
+any new `--meta` values.
+
+```bash
+# Tag a file at creation
+dftk eval raw.tsv -f "z = x + y" -o results.parquet \
+    --meta genome=hg38 --meta source=gwas_2024
+
+# Inspect annotations
+dftk annotate results.parquet
+# genome   hg38
+# source   gwas_2024
+
+# Add or update an annotation in-place
+dftk annotate results.parquet --set step=qc_filtered
+
+# Annotations survive piping
+dftk eval results.parquet -f "z_scaled = z / 2" -o | dftk scale ... -c z -o scaled.parquet
+dftk annotate scaled.parquet   # genome and source still present
+```
+
+## Figure options (plot commands)
+
+```text
+--size single|double|full|WxH    figure size (single ≈ 3.5", double ≈ 7.2")
+--fontsize screen|publication|presentation
+-f FILE                          save to file (PNG/PDF/SVG); omit to display
+--groupcol COL                   colour-code by this column
+--subgraphcol COL                split into subplot grid by this column
+--ncols N                        columns in subplot grid (default: auto)
+--legend TEXT                    legend label for ungrouped series
+```
+
+## Dependencies
+
+- `pandas`, `numpy`, `scipy` — core data handling and statistics
+- `statsmodels` — regression (`fit`, `scale --resid`, `wstat`)
+- `duckdb` — SQL queries (`query --sql`)
+- `matplotlib`, `seaborn` — plots
+- `pyarrow` — parquet I/O backend

dataframe_toolkit-0.4.1.dist-info/RECORD

@@ -0,0 +1,42 @@
+dftk/__init__.py,sha256=Gp46arZlP72ZfUKQ9K13fR4_3ZbdGezi1PPQVaEkcFU,138
+dftk/cli.py,sha256=o6PR9H10cYXUnS8nce0sJR0V6RoNSgIZP4jbWc2u7U4,2239
+dftk/commands/__init__.py,sha256=RhY0u6TCU1c4hzE6O1vFofvpjxuPuuA00LHa3k54jcM,3437
+dftk/commands/annotate_cmd.py,sha256=TS_1Be2AqqYCAyJTV8XLbdTq9OizmLo2-3mha14X1ck,5212
+dftk/commands/base.py,sha256=zH_OPSmkAniB0ii7I-UC5ePS__Bb9glIMzL97hLl5U8,2938
+dftk/commands/binx_cmd.py,sha256=qk5rV-jv4dLo-FCKV5g4hVm09uwbyw1rC-rxFNQJID0,3897
+dftk/commands/clean_cmd.py,sha256=OIDjkCCxXqQGb6sFwGNnukj9z-Z_X52Y0-UhvBLMoYo,1537
+dftk/commands/concat_cmd.py,sha256=BWB005QDsg4u3_Y8gHKT2jm5wDm-fBRvNCJlCop_23I,4978
+dftk/commands/corr_cmd.py,sha256=w4MH0RRgTp497LDCFSY6VCIAGZGTB6UNRh8fZJ-rIhY,9095
+dftk/commands/dataset_cmd.py,sha256=CZ9Yt15TchCosE_ha6ydzRMwuCZVoT62qlL11iRp9I0,5411
+dftk/commands/describe_cmd.py,sha256=tE6Vn3iISxSJAkgeN0jSQ1_duCwYA1IvfA1Zsmu9f6s,11839
+dftk/commands/eval_cmd.py,sha256=pQy4oycLqIxk9GbfNruQd7AbZTvhVeOHrvOs59X0WKY,21896
+dftk/commands/fit_cmd.py,sha256=39hQERm8-YISGIb7brJSytyRQnZ3-efJ12Yldpuok8A,8352
+dftk/commands/func_cmd.py,sha256=Sbi2OeR3koxnzOJdHzjIZShmM021Xg-y4yJLjSG15rw,5809
+dftk/commands/help.py,sha256=yEVgLmos4MRDYlCHJJpUYToGhbumHEGiuRrKfq_lXFU,2172
+dftk/commands/hist_cmd.py,sha256=UCmfaSPMwX3c0ZllcDrw65andd0X1pj4eQnaa1xToEc,9490
+dftk/commands/interp_cmd.py,sha256=bZYU7SUz2D0j0IB3-HE999FXqNbP3wazSmYYRYDQSko,8503
+dftk/commands/line_cmd.py,sha256=TstXMOc5p99ShIdOexpg74RPl10LmiWTniGdDwLr_ww,9877
+dftk/commands/melt_cmd.py,sha256=7aYKOKx4zMv52w5P75n_48OdHgUiQI2_ZF5J0_lBy-A,2019
+dftk/commands/merge_cmd.py,sha256=WRtbWWkorF_Bt9jZHivh5Q-GhGAFO7un9w4DQL7WjlQ,11972
+dftk/commands/pivot_cmd.py,sha256=A8J2pCgihJBt-EpczQiZ3TwJg3b7w57y78dMKE_3VJ8,14143
+dftk/commands/print_cmd.py,sha256=SxXxIfkTwRvxVQ12kgyDrLc6nYp0AgfD6UdPw4dKXLI,1077
+dftk/commands/query_cmd.py,sha256=oiQxzHQxv8rFtANcNtI6lk_-mxur_fxcn9KBpf8ontY,7428
+dftk/commands/randvar_cmd.py,sha256=5dj81YbraOdK5xna5nKKAFJFSh0Ojd77xbSr1efP9Us,6358
+dftk/commands/sample_cmd.py,sha256=9KQEwp7p_DFD6nhTRT5-29yS0lTtiQKFOzTWDgX0aRY,3666
+dftk/commands/scale_cmd.py,sha256=M3u_o1uRvO6mxiRDLlo0KCDDpCHTa3s3hS17zGa7KdY,9668
+dftk/commands/scat_cmd.py,sha256=1bc9TXcgvWvjVfKEaEWixVua_EggDldZVY4sTd4QaWk,8816
+dftk/commands/split_cmd.py,sha256=uq7f0rgLYfi6ec7BO8M6SPOdwXM4pDqnwD17a9N7WxQ,3668
+dftk/commands/stat_cmd.py,sha256=Ct15RVGJ24125cYPydx_y6K5pwhji0eca8CW6EnvaBo,8916
+dftk/commands/test_cmd.py,sha256=rbBPA3J0HaLQFvh9qnvra2cBJ-D5r2WFFryuIHyZTfM,7550
+dftk/commands/wstat_cmd.py,sha256=i_Vn2k60yHGTVf56NPlRF3yH4CT9o69OKJPaI9wHp7Q,4575
+dftk/common/__init__.py,sha256=s9-EGsv9ITWJWnXcWB8k5eHxUvf8mN18qs8WEAyhZqo,340
+dftk/common/io.py,sha256=eJNZHEi77e1nH4op803IS9HDF4kKJKt_4CDp60Vd9nA,24956
+dftk/common/plot.py,sha256=FZ1sfXgmg3z_GLBLDi8hqKhDy4B9NVI-ehNYa0zvStw,17846
+dftk/common/seed.py,sha256=GdOUIu4Y3Kv9dIazuciBrVoRb1OLJ4NGgTu7BE3dGwE,863
+dftk/common/seq.py,sha256=iohaxp8-56CGWb_bsxSvt8AUk5QhHlb9vMuPgVZF_ow,4489
+dftk/common/stats.py,sha256=5dVy7J_9CudHPJYk6lrisQ3JLuSikzhqDT5YW1o_j0k,6745
+dftk/io.py,sha256=LpVW3AbvPPl1GOdFxAuK23_eNgIiLFbhtAF1Zo9Gogo,285
+dataframe_toolkit-0.4.1.dist-info/WHEEL,sha256=r-Se0i_n47Mj8pdnVuq7W628oP9YAKMaTjp4l3lQcns,81
+dataframe_toolkit-0.4.1.dist-info/entry_points.txt,sha256=UmzJ50KmmTmZ7YygucsEmenPTXWmRKJMYpimPyBodQc,40
+dataframe_toolkit-0.4.1.dist-info/METADATA,sha256=FzGggE9lxY3hpMYrmnGSxWWSI2affgcOH1d2My5iFNo,9286
+dataframe_toolkit-0.4.1.dist-info/RECORD,,

dataframe_toolkit-0.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.31
+Root-Is-Purelib: true
+Tag: py3-none-any

dataframe_toolkit-0.4.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dftk = dftk.cli:main
+

dftk/__init__.py

@@ -0,0 +1,4 @@
+# dftk — DataFrame analysis and manipulation toolkit
+from importlib.metadata import version
+
+__version__ = version("dataframe-toolkit")

dftk/cli.py

@@ -0,0 +1,72 @@
+"""
+dftk.cli — entry point for the ``dftk`` command.
+
+All subcommands are discovered through the COMMANDS list in
+dftk/commands/__init__.py.  This file contains no command-specific
+logic and never needs to change when a new subcommand is added.
+"""
+
+import argparse
+import logging
+import sys
+
+from dftk import __version__
+from dftk.commands import COMMANDS
+from dftk.common.io import DFTK_TMPDIR
+
+logger = logging.getLogger("dftk")
+logging.basicConfig(format="%(asctime)s %(module)s %(message)s", level=logging.INFO)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="dftk",
+        description="DataFrame analysis and manipulation toolkit.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Pipe mode — use -o alone to pass data between commands:\n"
+            "  dftk stat -g grp -s val -o \\\n"
+            "    | dftk pivot -i grp -v val_mean -o \\\n"
+            "    | dftk print\n\n"
+            f"Temp pipe files are stored in {DFTK_TMPDIR}\n"
+            "Run 'dftk clean' to remove any leftover pipe files."
+        ),
+    )
+
+    parser.add_argument("--version", action="version", version=f"dftk {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND")
+    subparsers.required = True
+
+    for cmd in COMMANDS:
+        cmd_parser = subparsers.add_parser(cmd.name, help=cmd.help)
+        cmd.add_arguments(cmd_parser)
+        cmd_parser.set_defaults(command_instance=cmd)
+
+    args = parser.parse_args()
+
+    try:
+        args.command_instance.execute(args)
+    except FileNotFoundError as exc:
+        print(f"File error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except ValueError as exc:
+        print(f"Input error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except RuntimeError as exc:
+        print(f"Processing error: {exc}", file=sys.stderr)
+        sys.exit(1)
+    except Exception as exc:
+        import traceback
+
+        print(
+            f"Unexpected error ({type(exc).__name__}): {exc}\n"
+            "Please report this with the full traceback below.",
+            file=sys.stderr,
+        )
+        traceback.print_exc(file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

dftk/commands/__init__.py

@@ -0,0 +1,100 @@
+# dftk.commands — explicit registry of all dftk subcommands.
+#
+# To add a new subcommand:
+#   1. Create src/dftk/commands/<name>.py with a class that inherits
+#      from BaseCommand (see base.py for the contract and an example skeleton).
+#   2. Import the class here and add an instance to command_list below.
+#   That's it — cli.py discovers commands solely through this COMMANDS list.
+
+from dftk.commands.annotate_cmd import AnnotateCommand
+from dftk.commands.binx_cmd import BinxCommand
+from dftk.commands.clean_cmd import CleanCommand
+from dftk.commands.concat_cmd import ConcatCommand
+from dftk.commands.corr_cmd import CorrCommand
+from dftk.commands.dataset_cmd import DatasetCommand
+from dftk.commands.describe_cmd import DescribeCommand
+from dftk.commands.eval_cmd import EvalCommand
+from dftk.commands.fit_cmd import FitCommand
+from dftk.commands.func_cmd import FuncCommand
+from dftk.commands.help import HelpCommand
+from dftk.commands.hist_cmd import HistCommand
+from dftk.commands.interp_cmd import InterpCommand
+from dftk.commands.line_cmd import LineCommand
+from dftk.commands.melt_cmd import MeltCommand
+from dftk.commands.merge_cmd import MergeCommand
+from dftk.commands.pivot_cmd import PivotCommand
+from dftk.commands.print_cmd import PrintCommand
+from dftk.commands.query_cmd import QueryCommand
+from dftk.commands.randvar_cmd import RandvarCommand
+from dftk.commands.sample_cmd import SampleCommand
+from dftk.commands.scale_cmd import ScaleCommand
+from dftk.commands.scat_cmd import ScatCommand
+from dftk.commands.split_cmd import SplitCommand
+from dftk.commands.stat_cmd import StatCommand
+from dftk.commands.test_cmd import TestCommand
+from dftk.commands.wstat_cmd import WstatCommand
+
+# Ported subcommands — uncomment as each one is added:
+# from dftk.commands.segid     import SegidCommand
+# from dftk.commands.info      import InfoCommand
+# from dftk.commands.transpose import TransposeCommand
+# from dftk.commands.color     import ColorCommand
+# from dftk.commands.wavelet   import WaveletCommand
+# from dftk.commands.fisher    import FisherCommand  # superseded by eval's
+#                                                         # fisher_test/fisher_OR
+
+COMMAND_GROUPS: list[tuple[str, list]] = [
+    (
+        "Data transformation",
+        [
+            EvalCommand(),
+            QueryCommand(),
+            MergeCommand(),
+            ConcatCommand(),
+            MeltCommand(),
+            PivotCommand(),
+            FuncCommand(),
+            ScaleCommand(),
+            InterpCommand(),
+            BinxCommand(),
+        ],
+    ),
+    (
+        "Statistics",
+        [
+            StatCommand(),
+            WstatCommand(),
+            FitCommand(),
+            TestCommand(),
+            CorrCommand(),
+            DescribeCommand(),
+            RandvarCommand(),
+        ],
+    ),
+    (
+        "Plots",
+        [
+            ScatCommand(),
+            LineCommand(),
+            HistCommand(),
+        ],
+    ),
+    (
+        "Utilities",
+        [
+            DatasetCommand(),
+            SampleCommand(),
+            SplitCommand(),
+            AnnotateCommand(),
+            PrintCommand(),
+            CleanCommand(),
+        ],
+    ),
+]
+
+command_list = [cmd for _, cmds in COMMAND_GROUPS for cmd in cmds]
+
+# HelpCommand receives the live list and groups so it can introspect any peer.
+help_command = HelpCommand(command_list, COMMAND_GROUPS)
+
+COMMANDS = command_list + [help_command]

dftk/commands/annotate_cmd.py

@@ -0,0 +1,165 @@
+"""
+dftk.commands.annotate_cmd — dftk annotate subcommand.
+
+Read and write provenance metadata embedded in parquet files.
+
+Parquet stores arbitrary key-value string pairs in the file-level schema
+metadata.  dftk uses this to carry provenance annotations (genome build,
+source dataset, processing steps, etc.) through a pipeline.
+
+Usage examples:
+
+  # List all annotations on a file
+  dftk annotate data.parquet
+
+  # Set / update annotations (modifies the file in-place)
+  dftk annotate data.parquet --set genome=hg38 --set source=gwas_2024
+
+  # Get a single annotation
+  dftk annotate data.parquet --get genome
+
+  # Remove an annotation
+  dftk annotate data.parquet --delete genome
+
+  # Embed annotations when writing parquet from any dftk command
+  dftk eval data.tsv -f "z = x + y" -o result.parquet \\
+      --meta genome=hg38 --meta source=my_pipeline
+
+Annotations propagate through the parquet pipe: a file annotated at
+creation is re-annotated on every subsequent -o write unless explicitly
+overridden.
+"""
+
+import argparse
+import sys
+
+import pyarrow.parquet as pq
+
+from dftk.commands.base import BaseCommand
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_meta(path: str) -> dict[str, str]:
+    """Return custom (non-pandas) schema metadata from *path*."""
+    schema = pq.read_schema(path)
+    raw = schema.metadata or {}
+    return {k.decode(): v.decode() for k, v in raw.items() if k != b"pandas"}
+
+
+def _write_meta(path: str, meta: dict[str, str]) -> None:
+    """Overwrite the custom metadata in the parquet file at *path* in-place."""
+    table = pq.read_table(path)
+    existing = table.schema.metadata or {}
+    # Keep the pandas key intact; replace everything else with *meta*
+    pandas_meta = {k: v for k, v in existing.items() if k == b"pandas"}
+    new_meta = {
+        **pandas_meta,
+        **{k.encode(): v.encode() for k, v in meta.items()},
+    }
+    table = table.replace_schema_metadata(new_meta)
+    pq.write_table(table, path)
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+class AnnotateCommand(BaseCommand):
+    @property
+    def name(self) -> str:
+        return "annotate"
+
+    @property
+    def help(self) -> str:
+        return "Read and write provenance metadata in parquet files"
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        import argparse as ap
+
+        parser.formatter_class = ap.RawDescriptionHelpFormatter
+        parser.description = __doc__
+
+        parser.add_argument(
+            "PARQUET",
+            help="Parquet file to inspect or annotate.",
+        )
+        parser.add_argument(
+            "--set",
+            dest="set_meta",
+            help="Set a metadata annotation (KEY=VALUE).  Repeatable.",
+            default=[],
+            action="append",
+            metavar="KEY=VALUE",
+        )
+        parser.add_argument(
+            "--get",
+            dest="get_key",
+            help="Print the value of a single annotation key.",
+            default=None,
+            metavar="KEY",
+        )
+        parser.add_argument(
+            "--delete",
+            dest="delete_keys",
+            help="Remove an annotation key.  Repeatable.",
+            default=[],
+            action="append",
+            metavar="KEY",
+        )
+        parser.add_argument(
+            "--clear",
+            help="Remove ALL custom annotations from the file.",
+            action="store_true",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        path: str = args.PARQUET
+
+        if not path.endswith(".parquet"):
+            print(
+                f"annotate: {path!r} does not appear to be a parquet file.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        # ---- mutations (--set / --delete / --clear) — applied first -------
+
+        if args.clear or args.set_meta or args.delete_keys:
+            meta = {} if args.clear else _read_meta(path)
+
+            for item in args.set_meta:
+                try:
+                    k, v = item.split("=", 1)
+                    meta[k.strip()] = v.strip()
+                except ValueError:
+                    print(
+                        f"annotate --set: expected KEY=VALUE, got {item!r}",
+                        file=sys.stderr,
+                    )
+                    sys.exit(1)
+
+            for key in args.delete_keys:
+                meta.pop(key, None)
+
+            _write_meta(path, meta)
+
+        # ---- read current state and respond --------------------------------
+
+        meta = _read_meta(path)
+
+        if args.get_key is not None:
+            value = meta.get(args.get_key)
+            if value is None:
+                print(
+                    f"annotate --get: key {args.get_key!r} not found.", file=sys.stderr
+                )
+                sys.exit(1)
+            print(value)
+        else:
+            # Default: list all annotations as TSV (key sorted)
+            for k, v in sorted(meta.items()):
+                print(f"{k}\t{v}")