tadclust 0.1.0a1__tar.gz

tadclust-0.1.0a1/.gitignore

@@ -0,0 +1,17 @@
+.*
+_*
+!.dockerignore
+!.gitattributes
+!.gitignore
+!.gitmodules
+!.github/
+!.python-version
+
+!__init__.py
+!__main__.py
+
+__pycache__/
+*.egg-info/
+build/
+out/
+dist/

tadclust-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) snsinfu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tadclust-0.1.0a1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: tadclust
+Version: 0.1.0a1
+Summary: Hierarchical clustering of TADs
+Project-URL: Homepage, https://github.com/snsinfu/tadclust
+Project-URL: Repository, https://github.com/snsinfu/tadclust
+Project-URL: Issues, https://github.com/snsinfu/tadclust/issues
+Author-email: snsinfu <snsinfu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: Hi-C,TAD,bioinformatics,hierarchical clustering,topologically associating domains
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cooler<0.11,>=0.10.4
+Requires-Dist: h5py<4,>=3.10
+Requires-Dist: numpy<3,>=2
+Requires-Dist: polars<2,>=1.30
+Requires-Dist: pyarrow
+Requires-Dist: scikit-learn<2,>=1.5
+Requires-Dist: scipy<2,>=1.11
+Requires-Dist: threadpoolctl>=3
+Description-Content-Type: text/markdown
+
+# TADCLUST - Hierarchical clustering of TADs
+
+Given any TAD annotation and a contact map, TADCLUST applies hierarchical clustering of the TADs based on TAD-level O/E matrix, to build a tree on each chromosome. The clustering analysis identifies a higher-order organization of locally-defined TADs, which is correlated to chromosome compartmentalization.
+
+![Example TADCLUST tree for human HL-60 chr10](assets/example_tree.webp)
+
+## Install
+
+TADCLUST is experimental and not released yet. Git clone, and use uv to try it out:
+
+```console
+$ git clone https://github.com/snsinfu/tadclust.git
+$ cd tadclust
+$ uv run tadclust -h
+````
+
+Or, use docker (currently not regularly updated):
+
+```console
+$ docker run --rm ghcr.io/snsinfu/tadclust tadclust -h
+```
+
+Installing to a uv/pixi project from the GitHub repository:
+
+```console
+$ uv add git+https://github.com/snsinfu/tadclust.git
+$ pixi add --pypi --git https://github.com/snsinfu/tadclust.git tadclust
+```
+
+## Usage
+
+Give an mcool contact matrix, a TAD annotation table, optionally an A/B feature track, and the output directory.
+
+```console
+$ tadclust \
+  --output-dir       out \
+  --mcool            contact_map.mcool \
+  --tad-table        tad_annotation.bed \
+  --ab-feature-track active_signal.bedGraph
+```
+
+The TAD table can be any disjoint or hierarchical TAD annotation in the BED3+ format, or a TSV with `chrom, start, end` columns. TADCLUST selects an optimal set of sub-TADs for clustering if the annotation is hierarchical. `--ab-feature-track` is any 4-column, BedGraph-like table or BED5+ where the annotated score is larger in the A compartment (like ATAC, H4ac, and gene density). It is used to define the A/B compartment boundary, to enable A/B annotation of TADs and cluster nodes.
+
+### Options
+
+| option              | default | description |
+|:--------------------|:--------|:------------|
+| --tree-branch-k  K  | 2       | Split count of recursive k-means. |
+| --with-trans        | no      | Enable trans-chromosomal clustering (experimental and expensive). |
+| --with-residuals    | no      | Fill gaps with `residual` pseudo-domains. |
+| --overwrite         | no      | Allow overwriting existing files in the output directory. |
+| --workers        N  | 1       | Run analysis in parallel using N processes. |
+| --seed           N  | 0       | Random seed for reproducibility. |
+
+### Output
+
+Results are stored as parquet/tsv tables and a json summary in the output directory:
+
+```
+out/
+├── cis_nodes.parquet
+├── cis_nodes_ab.parquet        # optional
+├── cis_leaves.parquet
+├── cis_leaves.tsv
+├── cis_leaves_ab.parquet       # optional
+├── cis_leaves_ab.tsv           # optional
+├── trans_nodes.parquet         # optional
+└── manifest.json
+```
+
+Main output is `cis_nodes.parquet` which contains full tree nodes for all chromosomes. `cis_leaves.{parquet,tsv}` are leaf-only subsets created for convenience. `_ab` suffixed tables store the result for A/B-rooted clustering variant. A copy of `manifest.json` is stored in every parquet file as a parquet metadata keyed by "tadclust"; the manifest contains version info, algorithm params, and QC stats.
+
+Columns in the main table:
+
+| column            | type             | description |
+|:------------------|:-----------------|:------------|
+| chrom             | string           | The chromosome the node belongs to. |
+| node_id           | int              | Unique ID of the node within the table. |
+| parent_id         | int              | Parent's node_id or null. |
+| child_ids         | int[]            | Children's node_ids or empty. |
+| depth             | int              | Depth of the node, 0 = root. |
+| is_leaf           | bool             | (leaf) True or (branch) false. |
+| unit_id           | int              | (leaf) Unique ID of the clustered leaf unit or (branch) null. |
+| unit_kind         | tad/residual/bin | (leaf) Type of the unit or (branch) null. |
+| unit_start        | int              | (leaf) Start coord of the unit or (branch) null. |
+| unit_end          | int              | (leaf) End coord of the unit or (branch) null. |
+| tad_table_row     | int              | (leaf) Row index of the TAD table or (branch/non-TAD) null. |
+| root_label        | chrom/A/B/genome | Root of the tree the node belongs to. |
+| path              | int[]            | Branches to take to arrive at the node from the root, like \[0,1,0,1,1,1\]. |
+| path_label        | string           | Root + path as a dot-delimited string, like "chrom.0.1.0.1.1.1". |
+| ab_label          | A/B              | A/B classification (ab_signal <=> 0) of the node. |
+| ab_signal         | float            | A/B compartment signal for the node. |
+| ab_frac_a         | float            | Fraction of A leaves under the node. |
+| ab_frac_b         | float            | Fraction of B leaves under the node. |
+| ab_purity         | float            | Max(ab_frac_a, ab_frac_b). |
+| pc                | float[]          | (leaf) PC feature vector or (branch) centroid. |
+| n_units           | int              | Number of units under the node. |
+| n_working_bins    | int              | Number of working bins covered by the units under the node. |
+| node_oe           | float            | Mean log2 O/E over all units and unit pairs under the node. |
+| node_internal_sse | float            | Feature-space SSE of leaves under the node. |
+| node_split_gain   | float            | Relative SSE cost of splitting at this node. |
+| stop_reason       | degenerate       | Reason of abruptly stopped splitting or null. |
+
+Notes:
+
+- Node's children (.0 .1) are ordered by centroid PC1.
+- When `--ab-feature-track` is given, the PC1 axis itself is oriented towards higher A signal. So nodes are B-to-A ordered.
+- In the tsv outputs, array/list columns are not emitted, and nulls are replaced by (int) -1, (float) NaN, and (string) "NA".
+
+## Method notes
+
+**TAD-level L2-normalized log-O/E** is diagonalized (without centering; zero is the natural center for log-O/E) to produce principal components. This PC feature space is hierarchically clustered like CALDER. The first branch gives a similar result to the conventional compartment analysis, and deeper branches describe subcompartment organization.
+
+When **hierarchical TAD annotation** is given (i.e., there are nested intervals), the optimal levels of sub-TAD hierarchies are decided by dynamic programming so that within-TAD variance (among sub-TADs and gaps) is minimized in the feature space. The selected (sub-)TADs are output as leaf units with `unit_kind` = "tad". Besides clustering, this selection of the "most coherent" sub-TADs can be useful on its own.
+
+**Recursive K-means** seems superior to other methods like Ward, HDBSCAN, spectral, etc. for clustering TADs. This is probably because the domains in the feature space are not cleanly separable (strong noise, broad lobes, and biological intermediates). Bisection (k=2) is good enough to maintain A/B coherence in subtree. k=3 performs similarly good.
+
+For **A/B compartment** annotation, an auxiliary binary split of an augmented feature space is made. Bisection of the raw PC space does not reliably give a useful "A/B"-like clusters except for mammalian datasets, so the PC space needs to be augmented by a reference signal track (`--ab-feature-track`; ATAC, H4ac, and gene density tracks work well) to determine the A/B decision boundary and the orientation. Once the boundary is determined, it is projected onto the original PC space, and the TADs are A/B-annotated. This auxiliary split is done solely for annotation and it does not affect the cluster hierarchy.
+
+The **A/B signal** is the 1D projection of the node's PC centroid onto the A-B axis in the PC space (the axis along the A and B centroids). This is a generalization of the conventional PC1 compartment signal to the bisected, higher-dimensional PC space. The magnitude of the signal is informative: it is the distance from the decision boundary, so close-to-zero signal indicates poor compartmentalization. The PC space is standardized in A/B analysis, so the typical values of the signal distribute in the ~3 sigma range, or within approximtely \[-3,3\], so the "normal" magnitude would be around ~1.
+
+**Genome-wide clustering** (experimental) is also done when `--with-trans` flag is passed. Genome-wide, trans-chrom O/E is built using the cis-defined TADs as units, diagonalized, and recursively clustered. The trans tree tends to capture chromosome territories or telomere clustering rather than genome-wide A/B compartments. Still, the `unit_id` is shared between the cis table, so one can JOIN cis and trans tables to examine cis-determined A/B on the trans tree.
+
+## AI disclosure
+
+LLM coding agent is used for development. Algorithm is designed and instructed by me, then implemented by AI, benchmarking on real datasets. I review every changeset and adjust it until it looks fine. This README is 100% human-written.
+
+## License
+
+MIT

tadclust-0.1.0a1/README.md

@@ -0,0 +1,130 @@
+# TADCLUST - Hierarchical clustering of TADs
+
+Given any TAD annotation and a contact map, TADCLUST applies hierarchical clustering of the TADs based on TAD-level O/E matrix, to build a tree on each chromosome. The clustering analysis identifies a higher-order organization of locally-defined TADs, which is correlated to chromosome compartmentalization.
+
+![Example TADCLUST tree for human HL-60 chr10](assets/example_tree.webp)
+
+## Install
+
+TADCLUST is experimental and not released yet. Git clone, and use uv to try it out:
+
+```console
+$ git clone https://github.com/snsinfu/tadclust.git
+$ cd tadclust
+$ uv run tadclust -h
+````
+
+Or, use docker (currently not regularly updated):
+
+```console
+$ docker run --rm ghcr.io/snsinfu/tadclust tadclust -h
+```
+
+Installing to a uv/pixi project from the GitHub repository:
+
+```console
+$ uv add git+https://github.com/snsinfu/tadclust.git
+$ pixi add --pypi --git https://github.com/snsinfu/tadclust.git tadclust
+```
+
+## Usage
+
+Give an mcool contact matrix, a TAD annotation table, optionally an A/B feature track, and the output directory.
+
+```console
+$ tadclust \
+  --output-dir       out \
+  --mcool            contact_map.mcool \
+  --tad-table        tad_annotation.bed \
+  --ab-feature-track active_signal.bedGraph
+```
+
+The TAD table can be any disjoint or hierarchical TAD annotation in the BED3+ format, or a TSV with `chrom, start, end` columns. TADCLUST selects an optimal set of sub-TADs for clustering if the annotation is hierarchical. `--ab-feature-track` is any 4-column, BedGraph-like table or BED5+ where the annotated score is larger in the A compartment (like ATAC, H4ac, and gene density). It is used to define the A/B compartment boundary, to enable A/B annotation of TADs and cluster nodes.
+
+### Options
+
+| option              | default | description |
+|:--------------------|:--------|:------------|
+| --tree-branch-k  K  | 2       | Split count of recursive k-means. |
+| --with-trans        | no      | Enable trans-chromosomal clustering (experimental and expensive). |
+| --with-residuals    | no      | Fill gaps with `residual` pseudo-domains. |
+| --overwrite         | no      | Allow overwriting existing files in the output directory. |
+| --workers        N  | 1       | Run analysis in parallel using N processes. |
+| --seed           N  | 0       | Random seed for reproducibility. |
+
+### Output
+
+Results are stored as parquet/tsv tables and a json summary in the output directory:
+
+```
+out/
+├── cis_nodes.parquet
+├── cis_nodes_ab.parquet        # optional
+├── cis_leaves.parquet
+├── cis_leaves.tsv
+├── cis_leaves_ab.parquet       # optional
+├── cis_leaves_ab.tsv           # optional
+├── trans_nodes.parquet         # optional
+└── manifest.json
+```
+
+Main output is `cis_nodes.parquet` which contains full tree nodes for all chromosomes. `cis_leaves.{parquet,tsv}` are leaf-only subsets created for convenience. `_ab` suffixed tables store the result for A/B-rooted clustering variant. A copy of `manifest.json` is stored in every parquet file as a parquet metadata keyed by "tadclust"; the manifest contains version info, algorithm params, and QC stats.
+
+Columns in the main table:
+
+| column            | type             | description |
+|:------------------|:-----------------|:------------|
+| chrom             | string           | The chromosome the node belongs to. |
+| node_id           | int              | Unique ID of the node within the table. |
+| parent_id         | int              | Parent's node_id or null. |
+| child_ids         | int[]            | Children's node_ids or empty. |
+| depth             | int              | Depth of the node, 0 = root. |
+| is_leaf           | bool             | (leaf) True or (branch) false. |
+| unit_id           | int              | (leaf) Unique ID of the clustered leaf unit or (branch) null. |
+| unit_kind         | tad/residual/bin | (leaf) Type of the unit or (branch) null. |
+| unit_start        | int              | (leaf) Start coord of the unit or (branch) null. |
+| unit_end          | int              | (leaf) End coord of the unit or (branch) null. |
+| tad_table_row     | int              | (leaf) Row index of the TAD table or (branch/non-TAD) null. |
+| root_label        | chrom/A/B/genome | Root of the tree the node belongs to. |
+| path              | int[]            | Branches to take to arrive at the node from the root, like \[0,1,0,1,1,1\]. |
+| path_label        | string           | Root + path as a dot-delimited string, like "chrom.0.1.0.1.1.1". |
+| ab_label          | A/B              | A/B classification (ab_signal <=> 0) of the node. |
+| ab_signal         | float            | A/B compartment signal for the node. |
+| ab_frac_a         | float            | Fraction of A leaves under the node. |
+| ab_frac_b         | float            | Fraction of B leaves under the node. |
+| ab_purity         | float            | Max(ab_frac_a, ab_frac_b). |
+| pc                | float[]          | (leaf) PC feature vector or (branch) centroid. |
+| n_units           | int              | Number of units under the node. |
+| n_working_bins    | int              | Number of working bins covered by the units under the node. |
+| node_oe           | float            | Mean log2 O/E over all units and unit pairs under the node. |
+| node_internal_sse | float            | Feature-space SSE of leaves under the node. |
+| node_split_gain   | float            | Relative SSE cost of splitting at this node. |
+| stop_reason       | degenerate       | Reason of abruptly stopped splitting or null. |
+
+Notes:
+
+- Node's children (.0 .1) are ordered by centroid PC1.
+- When `--ab-feature-track` is given, the PC1 axis itself is oriented towards higher A signal. So nodes are B-to-A ordered.
+- In the tsv outputs, array/list columns are not emitted, and nulls are replaced by (int) -1, (float) NaN, and (string) "NA".
+
+## Method notes
+
+**TAD-level L2-normalized log-O/E** is diagonalized (without centering; zero is the natural center for log-O/E) to produce principal components. This PC feature space is hierarchically clustered like CALDER. The first branch gives a similar result to the conventional compartment analysis, and deeper branches describe subcompartment organization.
+
+When **hierarchical TAD annotation** is given (i.e., there are nested intervals), the optimal levels of sub-TAD hierarchies are decided by dynamic programming so that within-TAD variance (among sub-TADs and gaps) is minimized in the feature space. The selected (sub-)TADs are output as leaf units with `unit_kind` = "tad". Besides clustering, this selection of the "most coherent" sub-TADs can be useful on its own.
+
+**Recursive K-means** seems superior to other methods like Ward, HDBSCAN, spectral, etc. for clustering TADs. This is probably because the domains in the feature space are not cleanly separable (strong noise, broad lobes, and biological intermediates). Bisection (k=2) is good enough to maintain A/B coherence in subtree. k=3 performs similarly good.
+
+For **A/B compartment** annotation, an auxiliary binary split of an augmented feature space is made. Bisection of the raw PC space does not reliably give a useful "A/B"-like clusters except for mammalian datasets, so the PC space needs to be augmented by a reference signal track (`--ab-feature-track`; ATAC, H4ac, and gene density tracks work well) to determine the A/B decision boundary and the orientation. Once the boundary is determined, it is projected onto the original PC space, and the TADs are A/B-annotated. This auxiliary split is done solely for annotation and it does not affect the cluster hierarchy.
+
+The **A/B signal** is the 1D projection of the node's PC centroid onto the A-B axis in the PC space (the axis along the A and B centroids). This is a generalization of the conventional PC1 compartment signal to the bisected, higher-dimensional PC space. The magnitude of the signal is informative: it is the distance from the decision boundary, so close-to-zero signal indicates poor compartmentalization. The PC space is standardized in A/B analysis, so the typical values of the signal distribute in the ~3 sigma range, or within approximtely \[-3,3\], so the "normal" magnitude would be around ~1.
+
+**Genome-wide clustering** (experimental) is also done when `--with-trans` flag is passed. Genome-wide, trans-chrom O/E is built using the cis-defined TADs as units, diagonalized, and recursively clustered. The trans tree tends to capture chromosome territories or telomere clustering rather than genome-wide A/B compartments. Still, the `unit_id` is shared between the cis table, so one can JOIN cis and trans tables to examine cis-determined A/B on the trans tree.
+
+## AI disclosure
+
+LLM coding agent is used for development. Algorithm is designed and instructed by me, then implemented by AI, benchmarking on real datasets. I review every changeset and adjust it until it looks fine. This README is 100% human-written.
+
+## License
+
+MIT

tadclust-0.1.0a1/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tadclust"
+dynamic = ["version"]
+description = "Hierarchical clustering of TADs"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "snsinfu", email = "snsinfu@gmail.com" }]
+keywords = [
+  "Hi-C",
+  "TAD",
+  "topologically associating domains",
+  "hierarchical clustering",
+  "bioinformatics",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+  "Typing :: Typed",
+]
+dependencies = [
+  "cooler>=0.10.4,<0.11",
+  "h5py>=3.10,<4",
+  "numpy>=2,<3",
+  "polars>=1.30,<2",
+  "pyarrow",
+  "scikit-learn>=1.5,<2",
+  "scipy>=1.11,<2",
+  "threadpoolctl>=3",
+]
+
+[project.scripts]
+tadclust = "tadclust.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/snsinfu/tadclust"
+Repository = "https://github.com/snsinfu/tadclust"
+Issues = "https://github.com/snsinfu/tadclust/issues"
+
+[dependency-groups]
+dev = [
+  "pandas",
+  "pyright",
+  "pytest",
+  "ruff",
+]
+
+[tool.hatch.version]
+path = "src/tadclust/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tadclust"]
+exclude = ["**/__pycache__", "**/*.pyc"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/tadclust",
+  "tests",
+  "pyproject.toml",
+  "README.md",
+  "LICENSE",
+]
+exclude = ["**/__pycache__", "**/*.pyc"]

tadclust-0.1.0a1/src/tadclust/__init__.py

@@ -0,0 +1,11 @@
+"""Hierarchical clustering of TADs."""
+
+from __future__ import annotations
+
+from .config import ClusterConfig
+from .metadata import read_manifest
+from .pipeline import ClusterResult, cluster
+
+__version__ = "0.1.0a1"
+
+__all__ = ["ClusterConfig", "ClusterResult", "__version__", "cluster", "read_manifest"]

tadclust-0.1.0a1/src/tadclust/__main__.py

@@ -0,0 +1,7 @@
+"""Run the tadclust command-line interface."""
+
+from __future__ import annotations
+
+from .cli import main
+
+main()

tadclust-0.1.0a1/src/tadclust/bedlike.py

@@ -0,0 +1,102 @@
+"""Shared reader for tab-separated BED-like tables."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TextIO
+
+import polars as pl
+
+type SchemaFactory = Callable[[bool, int], dict[str, type]]
+
+
+@dataclass(frozen=True)
+class BedlikeTable:
+    """A parsed table plus the header and width inferred from its first line."""
+
+    table: pl.DataFrame
+    has_header: bool
+    width: int
+
+
+def read_bedlike(
+    path: str | Path,
+    *,
+    header_names: Sequence[str] | None = None,
+    schema_overrides: dict[str, type] | SchemaFactory,
+    skip_track_headers: bool = False,
+) -> BedlikeTable:
+    """Read a tab-separated table, inferring header presence and width.
+
+    Leading blank, comment, and (optionally) track/browser lines are skipped.
+    Callers provide the schema, either directly or as a function of whether a
+    header was found and how many columns the first line has.
+    """
+    source = Path(path)
+    with source.open("r", encoding="utf-8", newline="") as handle:
+        sample, skip_lines = _sample_lines(handle, skip_track_headers)
+        if not sample:
+            raise ValueError(f"empty table: {source}")
+
+        first_line = sample[0]
+        width = len(first_line.split("\t"))
+        tokens = {token.strip() for token in first_line.split("\t")}
+        has_header = header_names is not None and set(header_names).issubset(tokens)
+
+        handle.seek(0)
+        schema = (
+            schema_overrides(has_header, width)
+            if callable(schema_overrides)
+            else schema_overrides
+        )
+        table = pl.read_csv(
+            handle,
+            separator="\t",
+            has_header=has_header,
+            comment_prefix="#",
+            infer_schema_length=0,
+            schema_overrides=schema,
+            skip_lines=skip_lines,
+            truncate_ragged_lines=False,
+        )
+
+    return BedlikeTable(
+        table=table,
+        has_header=has_header,
+        width=width,
+    )
+
+
+def _sample_lines(
+    handle: TextIO,
+    skip_track_headers: bool,
+    limit: int = 20,
+) -> tuple[list[str], int]:
+    sample: list[str] = []
+    skipped = 0
+    started = False
+
+    for line in handle:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            if not started:
+                skipped += 1
+            continue
+        if skip_track_headers and _is_track_header(stripped):
+            if not started:
+                skipped += 1
+            continue
+
+        sample.append(stripped)
+        started = True
+        if len(sample) >= limit:
+            break
+
+    return sample, skipped
+
+
+def _is_track_header(line: str) -> bool:
+    lower = line.lower()
+    return lower in {"track", "browser"} or lower.startswith(("track ", "browser "))