dataframe-toolkit 0.4.1__py3-none-any.whl

dftk/commands/hist_cmd.py

@@ -0,0 +1,321 @@
+"""
+dftk.commands.hist_cmd — dftk hist subcommand.
+
+Histogram or kernel density estimate (KDE).
+
+Port of dfhist.py with improvements:
+  - --groupcol  overlaid histograms / KDEs per group (colours from Wong palette)
+  - --subgraphcol  splits into a subplot grid
+  - --size / --fontsize  publication-quality figure presets
+  - --bins / --binwidth  bin control (mutual exclusion preserved)
+  - --kde  kernel density estimate via seaborn.kdeplot
+  - --stats  add mean ± σ to subplot title
+  - -y/--weightcol  renamed from --ycol for clarity (weights column)
+"""
+
+import argparse
+
+import numpy as np
+
+from dftk.commands.base import BaseCommand
+from dftk.common.io import check_cols, io
+from dftk.common.plot import (
+    add_figure_arguments,
+    add_group_arguments,
+    add_legend_arguments,
+    apply_labels,
+    apply_limits,
+    apply_style,
+    make_figure,
+    make_grouplabel,
+    save_or_show,
+    subgraph_groups,
+    subgraph_layout,
+)
+
+# ---------------------------------------------------------------------------
+# Single-axes histogram
+# ---------------------------------------------------------------------------
+
+
+def _hist_ax(ax, df, args, title_suffix: str = ""):
+    xcol = args.xcol
+    legendloc = tuple(args.legendloc) if args.legendloc else "best"
+
+    # Build bins
+    data_all = df[xcol].dropna()
+    bins = args.bins
+    if args.binwidth is not None and not args.kde:
+        lo = (data_all.min() // args.binwidth) * args.binwidth
+        hi = data_all.max() + args.binwidth
+        bins = np.arange(lo, hi, args.binwidth)
+
+    kde_bw = args.binwidth if args.kde and args.binwidth is not None else "scott"
+
+    hist_kw = dict(
+        alpha=0.4,
+        cumulative=args.cumulative,
+        density=args.normed,
+    )
+
+    if args.groupcol is not None:
+        for groupname, gdf in subgraph_groups(
+            df, args.groupcol, getattr(args, "groupcolorder", None)
+        ):
+            label = make_grouplabel(
+                groupname, args.groupcol, getattr(args, "groupcolformat", None)
+            )
+            data = gdf[xcol].dropna()
+            weights = gdf[args.weightcol].values if args.weightcol else None
+            if args.kde:
+                import seaborn as sns
+
+                sns.kdeplot(
+                    data,
+                    bw_method=kde_bw,
+                    label=label,
+                    cumulative=args.cumulative,
+                    cut=0,
+                    ax=ax,
+                )
+            else:
+                ax.hist(data, bins=bins, weights=weights, label=label, **hist_kw)
+        ax.legend(loc=legendloc, title=args.legendtitle)
+    else:
+        data = data_all
+        weights = df[args.weightcol].values if args.weightcol else None
+        label = args.legend or None
+
+        if args.stats:
+            mu, sigma = data.mean(), data.std()
+            stats_str = f"μ={mu:.3g}, σ={sigma:.3g}"
+            existing_title = title_suffix or args.title or ""
+            title_suffix = (
+                f"{existing_title}  ({stats_str})" if existing_title else stats_str
+            )
+
+        if args.kde:
+            import seaborn as sns
+
+            sns.kdeplot(
+                data,
+                bw_method=kde_bw,
+                label=label,
+                cumulative=args.cumulative,
+                cut=0,
+                ax=ax,
+            )
+        else:
+            ax.hist(data, bins=bins, weights=weights, label=label, **hist_kw)
+
+        if label:
+            ax.legend(loc=legendloc, title=args.legendtitle)
+
+    apply_limits(ax, args)
+    apply_labels(
+        ax,
+        args,
+        default_xlabel=xcol or "",
+        default_ylabel="density" if args.normed else "count",
+    )
+
+    title = args.title or ""
+    if title_suffix:
+        title = f"{title}  [{title_suffix}]" if title else title_suffix
+    ax.set_title(title)
+
+    ax.grid(True, linewidth=0.4, alpha=0.5)
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+_EPILOG = """\
+EXAMPLES
+--------
+Basic histogram (10 bins):
+
+  dftk hist data.tsv -x value
+
+Fixed bin width:
+
+  dftk hist data.tsv -x value --binwidth 0.5
+
+Normalised density:
+
+  dftk hist data.tsv -x value --normed
+
+Cumulative:
+
+  dftk hist data.tsv -x value --cumulative
+
+KDE (kernel density estimate):
+
+  dftk hist data.tsv -x value --kde
+
+Grouped (overlaid):
+
+  dftk hist data.tsv -x value -g group
+
+Subplot grid by condition:
+
+  dftk hist data.tsv -x value --subgraphcol condition -g group
+
+Add mean ± σ to title:
+
+  dftk hist data.tsv -x value --stats
+
+Weighted histogram:
+
+  dftk hist data.tsv -x value -y weight_col
+
+Publication figure (Nature single column, PDF):
+
+  dftk hist data.tsv -x value --size single --fontsize publication -f fig.pdf
+"""
+
+
+class HistCommand(BaseCommand):
+    name = "hist"
+    help = "Histogram or kernel density estimate (KDE)."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.formatter_class = argparse.RawDescriptionHelpFormatter
+        parser.epilog = _EPILOG
+
+        self.add_read_arguments(parser)
+        add_figure_arguments(parser)
+        add_group_arguments(parser)
+        add_legend_arguments(parser)
+
+        g = parser.add_argument_group("histogram options")
+        g.add_argument(
+            "-x", "--xcol", metavar="COL", required=True, help="Column to histogram."
+        )
+        g.add_argument(
+            "-y",
+            "--weightcol",
+            default=None,
+            metavar="COL",
+            help="Column to use as observation weights.",
+        )
+        g.add_argument(
+            "-xl",
+            "--xlabel",
+            default=None,
+            metavar="TEXT",
+            help="X-axis label (default: column name).",
+        )
+        g.add_argument(
+            "-yl",
+            "--ylabel",
+            default=None,
+            metavar="TEXT",
+            help="Y-axis label (default: count or density).",
+        )
+        g.add_argument(
+            "-xm",
+            "--xlim",
+            nargs=2,
+            metavar=("LO", "HI"),
+            default=None,
+            help="X-axis limits.",
+        )
+        g.add_argument(
+            "-ym",
+            "--ylim",
+            nargs=2,
+            metavar=("LO", "HI"),
+            default=None,
+            help="Y-axis limits.",
+        )
+        g.add_argument("-lx", "--logx", action="store_true", help="Logarithmic x axis.")
+        g.add_argument("-ly", "--logy", action="store_true", help="Logarithmic y axis.")
+        g.add_argument(
+            "--xmargin", action="store_true", help="Add 1 %% margin to x limits."
+        )
+        g.add_argument(
+            "--ymargin", action="store_true", help="Add 1 %% margin to y limits."
+        )
+
+        g.add_argument(
+            "-n",
+            "--normed",
+            action="store_true",
+            help="Normalise so area sums to 1 (density).",
+        )
+        g.add_argument(
+            "-c", "--cumulative", action="store_true", help="Plot cumulative histogram."
+        )
+        g.add_argument(
+            "-k",
+            "--kde",
+            action="store_true",
+            help="Plot kernel density estimate instead of histogram "
+            "(uses seaborn.kdeplot).",
+        )
+        g.add_argument(
+            "--stats", action="store_true", help="Add mean ± σ to the subplot title."
+        )
+
+        bins = parser.add_argument_group("bin options (mutually exclusive)")
+        mx = bins.add_mutually_exclusive_group()
+        mx.add_argument(
+            "-b",
+            "--bins",
+            type=int,
+            default=10,
+            metavar="N",
+            help="Number of bins (default: 10).",
+        )
+        mx.add_argument(
+            "-w",
+            "--binwidth",
+            type=float,
+            default=None,
+            metavar="W",
+            help="Bin width (overrides --bins; also sets KDE bandwidth).",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        df = io.read(args)
+        check_cols(df, [args.xcol], "-x/--xcol")
+        check_cols(df, args.groupcol, "-g/--groupcol")
+        check_cols(df, args.subgraphcol, "--subgraphcol")
+        if args.weightcol:
+            check_cols(df, [args.weightcol], "-y/--weightcol")
+
+        if args.file:
+            import matplotlib
+
+            matplotlib.use("Agg")
+
+        import matplotlib.pyplot as plt
+
+        if getattr(args, "usetex", False):
+            plt.rc("text", usetex=True)
+
+        apply_style(args)
+
+        if args.subgraphcol is not None:
+            groups = subgraph_groups(
+                df, args.subgraphcol, getattr(args, "subgraphorder", None)
+            )
+            nrows, ncols = subgraph_layout(len(groups), args.ncols)
+            fig, axes = make_figure(args, nrows=nrows, ncols=ncols)
+            for idx, (groupname, gdf) in enumerate(groups):
+                ax = axes[idx // ncols][idx % ncols]
+                suffix = make_grouplabel(
+                    groupname, args.subgraphcol, getattr(args, "subgraphformat", None)
+                )
+                _hist_ax(ax, gdf, args, title_suffix=suffix)
+            for idx in range(len(groups), nrows * ncols):
+                axes[idx // ncols][idx % ncols].set_visible(False)
+            fig.tight_layout()
+        else:
+            fig, axes = make_figure(args)
+            _hist_ax(axes[0][0], df, args)
+            fig.tight_layout()
+
+        save_or_show(fig, args)

dftk/commands/interp_cmd.py

@@ -0,0 +1,271 @@
+"""
+dftk.commands.interp_cmd — dftk interp subcommand.
+
+Enriches a data table by interpolating values from a reference curve.
+
+The reference file (--ref) defines a 1-D function: a sorted x-column and one
+or more y-columns.  For each row in DATAFILE the command looks up the x-value
+in the reference and interpolates the corresponding y-value(s), appending them
+as new column(s).
+
+Grouping (-g) can be used when both files contain a grouping column (e.g. a
+chromosome or sample ID): interpolation is then performed independently within
+each matching group.
+
+INTERPOLATION METHODS (--method)
+---------------------------------
+  linear   (default) Piecewise-linear interpolation.
+  nearest  Nearest-neighbour (step function).
+  cubic    Cubic spline (requires >= 4 reference points per group).
+  zero     Zero-order hold (previous value).
+  slinear  Linear in the B-spline sense.
+  quadratic / cubic  Higher-order B-splines.
+
+Out-of-range behaviour (--fill)
+--------------------------------
+  nan    (default) Values outside the reference x-range are NaN.
+  edge   Clamp to the boundary values of the reference curve.
+
+KNOWN LIMITATION
+-----------------
+When the reference curve has a flat segment (zero slope, e.g. a recombination-
+cold spot in a genetic map), interpolation returns the left-boundary value for
+all query points within that segment.  Round-trip conversions that pass through
+a flat segment require manual handling — this command does not attempt to
+correct for it.
+
+EXAMPLES
+--------
+Basic interpolation — add "concentration" to samples by interpolating a
+standard curve:
+
+  dftk interp samples.tsv --ref stdcurve.tsv -x fluorescence -v concentration
+
+Different x-column names in each file:
+
+  dftk interp samples.tsv --ref stdcurve.tsv \\
+      -x sample_fluor --refx std_fluor -v concentration
+
+Interpolate multiple y-columns at once:
+
+  dftk interp data.tsv --ref ref.tsv -x pos -v y1 y2 -d col1 col2
+
+Per-chromosome genetic-map lookup (grouped):
+
+  dftk interp intervals.tsv --ref genmap.tsv \\
+      -x bp_mid --refx pos_bp -v pos_cM -d cM_mid -g chrom
+"""
+
+import argparse
+
+import numpy as np
+import pandas as pd
+
+from dftk.commands.base import BaseCommand
+from dftk.common.io import check_cols, io
+
+# ---------------------------------------------------------------------------
+# Core interpolation
+# ---------------------------------------------------------------------------
+
+
+def _interp_one(
+    ref: pd.DataFrame,
+    query: pd.DataFrame,
+    x_ref: str,
+    x_query: str,
+    val_cols: list[str],
+    dest_cols: list[str],
+    method: str,
+    fill: str,
+) -> pd.DataFrame:
+    """Interpolate *val_cols* from *ref* at *x_query* positions in *query*.
+
+    Returns a copy of *query* with *dest_cols* added.
+    """
+    import scipy.interpolate
+
+    query = query.copy()
+    x_new = query[x_query].to_numpy(dtype=float)
+
+    for src, dest in zip(val_cols, dest_cols, strict=False):
+        x_ref_arr = ref[x_ref].to_numpy(dtype=float)
+        y_ref_arr = ref[src].to_numpy(dtype=float)
+
+        if fill == "edge":
+            fv = (y_ref_arr[0], y_ref_arr[-1])
+        else:
+            fv = np.nan
+
+        fx = scipy.interpolate.interp1d(
+            x_ref_arr,
+            y_ref_arr,
+            kind=method,
+            bounds_error=False,
+            fill_value=fv,
+            assume_sorted=True,
+        )
+        query[dest] = fx(x_new)
+
+    return query
+
+
+def _interp(
+    ref: pd.DataFrame,
+    data: pd.DataFrame,
+    x_ref: str,
+    x_query: str,
+    val_cols: list[str],
+    dest_cols: list[str],
+    method: str,
+    fill: str,
+    groupcols: list[str] | None,
+) -> pd.DataFrame:
+    """Run interpolation, optionally within groups."""
+
+    if groupcols:
+        parts = []
+        # Both ref and data are grouped with the same groupcols, so keys match directly
+        ref_groups = {k: v for k, v in ref.groupby(groupcols)}
+        for grp_key, grp_data in data.groupby(groupcols, sort=False):
+            if grp_key not in ref_groups:
+                # Group present in data but not in ref — fill with NaN
+                grp_data = grp_data.copy()
+                for dest in dest_cols:
+                    grp_data[dest] = np.nan
+                parts.append(grp_data)
+                continue
+            parts.append(
+                _interp_one(
+                    ref_groups[grp_key],
+                    grp_data,
+                    x_ref,
+                    x_query,
+                    val_cols,
+                    dest_cols,
+                    method,
+                    fill,
+                )
+            )
+        return pd.concat(parts, ignore_index=True)
+
+    return _interp_one(ref, data, x_ref, x_query, val_cols, dest_cols, method, fill)
+
+
+# ---------------------------------------------------------------------------
+# Command
+# ---------------------------------------------------------------------------
+
+
+class InterpCommand(BaseCommand):
+    name = "interp"
+    help = "Enrich a table by interpolating values from a reference curve."
+
+    def add_arguments(self, parser: argparse.ArgumentParser) -> None:
+        parser.formatter_class = argparse.RawDescriptionHelpFormatter
+        parser.epilog = __doc__
+
+        self.add_io_arguments(parser)
+
+        g = parser.add_argument_group("interpolation options")
+        g.add_argument(
+            "--ref",
+            required=True,
+            metavar="FILE",
+            help="Reference file containing the curve to interpolate from.",
+        )
+        g.add_argument(
+            "-x",
+            "--xcol",
+            required=True,
+            metavar="COL",
+            help="X-axis column in DATAFILE (the query positions).",
+        )
+        g.add_argument(
+            "--refx",
+            default=None,
+            metavar="COL",
+            help="X-axis column in the reference file (default: same as -x/--xcol).",
+        )
+        g.add_argument(
+            "-v",
+            "--val",
+            required=True,
+            nargs="+",
+            metavar="COL",
+            help="Y-axis column(s) in the reference file to interpolate.",
+        )
+        g.add_argument(
+            "-d",
+            "--destcol",
+            default=None,
+            nargs="+",
+            metavar="NAME",
+            help="Output column name(s) in DATAFILE (default: same as -v/--val).",
+        )
+        g.add_argument(
+            "-g",
+            "--groupcol",
+            nargs="+",
+            default=None,
+            metavar="COL",
+            help=(
+                "Interpolate independently within each group. "
+                "Must be present in both DATAFILE and the reference file."
+            ),
+        )
+        g.add_argument(
+            "--method",
+            default="linear",
+            metavar="METHOD",
+            choices=["linear", "nearest", "zero", "slinear", "quadratic", "cubic"],
+            help="Interpolation method (default: linear).",
+        )
+        g.add_argument(
+            "--fill",
+            default="nan",
+            choices=["nan", "edge"],
+            help="Out-of-range fill: nan (default) or edge (clamp to boundary).",
+        )
+
+    def execute(self, args: argparse.Namespace) -> None:
+        # Read the data file (DATAFILE positional arg, handled by io.read)
+        data = io.read(args)
+
+        # Read the reference file using the same read settings
+        import copy
+
+        ref_args = copy.copy(args)
+        ref_args.DATAFILE = args.ref
+        ref = io.read(ref_args)
+
+        x_ref = args.refx if args.refx is not None else args.xcol
+        dest_cols = args.destcol if args.destcol is not None else list(args.val)
+
+        if len(dest_cols) != len(args.val):
+            raise ValueError(
+                f"--destcol has {len(dest_cols)} name(s) but "
+                f"--val has {len(args.val)} column(s). They must match."
+            )
+
+        # Validate columns
+        check_cols(data, [args.xcol], "-x/--xcol")
+        check_cols(data, args.groupcol, "-g/--groupcol")
+        check_cols(ref, [x_ref], "--refx")
+        check_cols(ref, args.val, "-v/--val")
+        if args.groupcol:
+            check_cols(ref, args.groupcol, "-g/--groupcol (in ref file)")
+
+        result = _interp(
+            ref=ref,
+            data=data,
+            x_ref=x_ref,
+            x_query=args.xcol,
+            val_cols=list(args.val),
+            dest_cols=dest_cols,
+            method=args.method,
+            fill=args.fill,
+            groupcols=args.groupcol,
+        )
+
+        io.printdf(result, args)