osteosarc 0.1.0__py3-none-any.whl

osteosarc/__init__.py

@@ -0,0 +1,34 @@
+"""Reproducible access to osteosarc.com. Importing performs no network I/O."""
+
+from .cache import Cache, Receipt, digest
+from .catalog import SNAPSHOT_SOURCES, TABLE_SOURCES, TIMELINE_SOURCES
+from .curation import CORRECTIONS, Change, Correction, CurationWarning, glob
+from .dataset import Dataset
+from .discovery import list_bucket
+from .errors import CoordinateError, IntegrityError, OfflineError, OsteosarcError, SchemaError
+from .models import Asset, Assets, Region, SampleClaim, Variant, Variants
+from .parsing import Table, parse_file, parse_table, parse_variant_index, parse_variants
+from .reads import (
+    AlignmentInfo,
+    ReadFilter,
+    ReadSubset,
+    assembly_from_header,
+    extract_reads,
+    inspect_alignment,
+    normalize_assembly,
+    resolve_regions,
+    subset_templates,
+)
+from .timeline import Event, Timeline
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AlignmentInfo", "Asset", "Assets", "CORRECTIONS", "Cache", "Change", "CoordinateError", "Correction",
+    "CurationWarning", "Dataset", "Event", "IntegrityError", "TIMELINE_SOURCES", "Timeline", "glob",
+    "OfflineError", "OsteosarcError", "ReadFilter", "ReadSubset", "Receipt", "Region",
+    "SNAPSHOT_SOURCES", "SampleClaim", "SchemaError", "TABLE_SOURCES", "Table", "Variant",
+    "Variants", "assembly_from_header", "digest", "extract_reads", "inspect_alignment", "list_bucket",
+    "normalize_assembly", "parse_file", "parse_table", "parse_variant_index", "parse_variants",
+    "resolve_regions", "subset_templates",
+]

osteosarc/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

osteosarc/cache.py

@@ -0,0 +1,292 @@
+"""Verified, shared, content-addressed downloads (curl; Linux and macOS).
+
+Files live in the OpenVax shared cache, the same layout vaxrank and other
+OpenVax tools use, so identical bytes are stored once:
+
+    <root>/objects/sha256/<sha256><original suffixes>   shared content
+    <root>/osteosarc/...                                 osteosarc's own records
+
+<root> is OSTEOSARC_CACHE (an isolated cache), else OPENVAX_DATA_CACHE, else
+the platform cache directory for "openvax" (as appdirs/datacache choose it).
+"""
+
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import unquote, urlsplit
+
+from .errors import IntegrityError, OfflineError
+
+
+def digest(path, algorithm="sha256"):
+    """Hash a file incrementally, without loading large alignments into RAM."""
+    return digests(path, (algorithm,))[algorithm]
+
+
+def digests(path, algorithms=("sha256",)):
+    """Several hashes of a file in one read."""
+    results = {name: hashlib.new(name) for name in algorithms}
+    with Path(path).open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            for result in results.values():
+                result.update(block)
+    return {name: result.hexdigest() for name, result in results.items()}
+
+
+def file_identity(path):
+    """Size, modification time and inode: changes whenever a file is rewritten."""
+    status = Path(path).stat()
+    return [str(Path(path).resolve()), status.st_size, status.st_mtime_ns, status.st_ino, status.st_dev]
+
+
+_UMASK = os.umask(0)
+os.umask(_UMASK)
+
+
+def share(path):
+    """Give files the permissions the process umask allows (mkstemp/mkdtemp default to owner-only)."""
+    os.chmod(path, (0o777 if Path(path).is_dir() else 0o666) & ~_UMASK)
+
+
+def default_root():
+    """The shared OpenVax cache root, resolved exactly as vaxrank/datacache resolve it."""
+    if os.environ.get("OPENVAX_DATA_CACHE"):
+        return Path(os.environ["OPENVAX_DATA_CACHE"])
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Caches" / "openvax"
+    return Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "openvax"
+
+
+def object_name(sha256, filename):
+    """OpenVax content name: the SHA256 followed by the original file's suffixes."""
+    return sha256 + "".join(Path(filename).suffixes)
+
+
+def stable_id(value):
+    """Return a deterministic SHA256 identity for a JSON-serializable value."""
+    return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def write_json(path, value):
+    """Atomically replace a JSON file on the same filesystem."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, name = tempfile.mkstemp(dir=path.parent, prefix=".json-")
+    try:
+        with os.fdopen(fd, "w") as handle:
+            json.dump(value, handle, indent=2, sort_keys=True)
+            handle.write("\n")
+        share(name)
+        os.replace(name, path)
+    finally:
+        Path(name).unlink(missing_ok=True)
+
+
+@contextmanager
+def file_lock(path):
+    """Serialize writers; OS releases the advisory lock after interruption."""
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a") as handle:
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)
+
+
+@dataclass(frozen=True)
+class Receipt:
+    url: str
+    sha256: str
+    size: int
+    filename: str
+    retrieved_at: str
+    etag: str | None = None
+    last_modified: str | None = None
+    md5: str | None = None
+
+    def to_dict(self):
+        return asdict(self)
+
+
+class Cache:
+    """A shared cache. Construction does no I/O; fetching is always explicit.
+
+    root defaults to OSTEOSARC_CACHE, else the OpenVax shared cache (see the
+    module docstring). Content is shared under objects/sha256; receipts,
+    snapshots and derived reads are kept under osteosarc/. Existing objects are
+    verified on every fetch. Refresh changes the URL's latest receipt but never
+    removes old snapshot objects.
+    """
+
+    def __init__(self, root=None, *, offline=False, timeout=600):
+        self.root = Path(root or os.environ.get("OSTEOSARC_CACHE") or default_root()).expanduser().resolve()
+        self.objects = self.root / "objects" / "sha256"
+        self.workspace = self.root / "osteosarc"
+        self.offline = offline
+        self.timeout = timeout
+        self._verified = {}
+
+    def path(self, receipt, *, verify=True):
+        """Resolve a receipt, detecting missing or modified bytes.
+
+        Each object is hashed once per Cache instance; a rewritten file (new
+        size, mtime or inode) is hashed again.
+        """
+        if not isinstance(receipt, Receipt):
+            receipt = Receipt(**receipt)
+        if (len(receipt.sha256) != 64 or any(c not in "0123456789abcdef" for c in receipt.sha256)
+                or Path(receipt.filename).name != receipt.filename or receipt.filename in ("", ".", "..")):
+            raise IntegrityError("Invalid cache receipt path")
+        path = self.objects / object_name(receipt.sha256, receipt.filename)
+        if not path.is_file():
+            raise OfflineError(f"Cached object is missing: {receipt.url}")
+        if verify:
+            identity = json.dumps(file_identity(path))
+            if self._verified.get(identity) != receipt.sha256:
+                if path.stat().st_size != receipt.size or digest(path) != receipt.sha256:
+                    raise IntegrityError(f"Cached object was modified: {path}")
+                self._verified[identity] = receipt.sha256
+        return path
+
+    def file_digest(self, path):
+        """SHA256 of a local file, remembered on disk by file identity.
+
+        Local BAMs are large; an unchanged file (same size, mtime and inode) is
+        not re-read. Any rewrite changes its identity and forces a new hash.
+        """
+        identity = file_identity(path)
+        memo = self.workspace / "digests" / (stable_id(identity) + ".json")
+        if memo.is_file():
+            record = json.loads(memo.read_text())
+            if record.get("identity") == identity:
+                return record["sha256"]
+        value = digest(path)
+        if file_identity(path) == identity:
+            write_json(memo, dict(identity=identity, sha256=value))
+        return value
+
+    def fetch(self, url, *, refresh=False, sha256=None, md5=None, size=None, max_bytes=None):
+        """Download or verify cached bytes, returning their immutable receipt.
+
+        Optional checksums are upstream claims checked against actual bytes;
+        ETags are retained as opaque HTTP identities, never treated as MD5s.
+        Interrupted downloads are discarded and retried on the next call.
+        """
+        if urlsplit(url).scheme not in ("https", "http"):
+            raise ValueError("Downloads require an HTTP(S) URL; use Cache.import_file for local data")
+        if refresh and self.offline:
+            raise OfflineError("Cannot refresh in offline mode")
+        pointer = self.workspace / "urls" / (stable_id(url) + ".json")
+        with file_lock(self.workspace / "locks" / (stable_id(url) + ".lock")):
+            if pointer.exists() and not refresh:
+                receipt = Receipt(**json.loads(pointer.read_text()))
+                if receipt.url != url:
+                    raise IntegrityError("Cache URL mismatch")
+                try:
+                    path = self.path(receipt)
+                except OfflineError:
+                    if self.offline:
+                        raise
+                    path = None  # the object was pruned; download it again below
+                if path is not None:
+                    # path() verified sha256; an md5 already checked when the object was stored is not re-read.
+                    known_md5 = md5 and receipt.md5 and md5.lower() == receipt.md5.lower()
+                    self._validate(path, sha256=None if sha256 == receipt.sha256 else sha256,
+                                   md5=None if known_md5 else md5, size=size, max_bytes=max_bytes)
+                    return receipt
+            if self.offline:
+                raise OfflineError(f"Not cached: {url}")
+            staging = self.workspace / "staging"
+            staging.mkdir(parents=True, exist_ok=True)
+            with tempfile.TemporaryDirectory(dir=staging) as temporary:
+                path = Path(temporary) / "download"
+                headers = Path(temporary) / "headers"
+                command = ["curl", "--fail", "--location", "--silent", "--show-error",
+                           "--proto", "=http,https", "--proto-redir", "=http,https",
+                           "--connect-timeout", "30", "--max-time", str(self.timeout),
+                           "--retry", "2", "--retry-all-errors",
+                           "--dump-header", str(headers), "--output", str(path)]
+                if max_bytes is not None:
+                    command += ["--max-filesize", str(max_bytes)]
+                subprocess.run(command + [url], check=True, capture_output=True,
+                               timeout=self.timeout * 3 + 120)
+                hashes = digests(path, ("sha256", "md5") if md5 else ("sha256",))
+                self._validate(path, sha256=sha256, md5=md5, size=size, max_bytes=max_bytes, hashes=hashes)
+                # Keep the final HTTP response, rather than a redirect's headers.
+                final = headers.read_text().strip().split("\n\n")[-1]
+                fields = {k.lower(): v.strip() for line in final.splitlines()
+                          if ":" in line for k, v in [line.split(":", 1)]}
+                receipt = self._store(path, url, fields, md5, move=True, checksum=hashes["sha256"])
+            write_json(pointer, receipt.to_dict())
+            return receipt
+
+    def import_file(self, path, url, *, sha256=None, md5=None, size=None):
+        """Adopt an already downloaded file with its original source URL.
+
+        Does not assert when the upstream object was downloaded. retrieved_at
+        records the local import time. Useful for existing project caches.
+        """
+        with file_lock(self.workspace / "locks" / (stable_id(url) + ".lock")):
+            path = Path(path)
+            self._validate(path, sha256=sha256, md5=md5, size=size)
+            receipt = self._store(path, url, {}, md5)
+            write_json(self.workspace / "urls" / (stable_id(url) + ".json"), receipt.to_dict())
+            return receipt
+
+    @staticmethod
+    def _validate(path, *, sha256=None, md5=None, size=None, max_bytes=None, hashes=None):
+        if size is not None and path.stat().st_size != size:
+            raise IntegrityError(f"Size mismatch: {path}")
+        if max_bytes is not None and path.stat().st_size > max_bytes:
+            raise IntegrityError(f"Download exceeds {max_bytes} bytes")
+        wanted = {name: value for name, value in (("sha256", sha256), ("md5", md5)) if value is not None}
+        if wanted:
+            hashes = dict(hashes or {})
+            missing = tuple(name for name in wanted if name not in hashes)
+            hashes.update(digests(path, missing) if missing else {})
+            for algorithm, expected in wanted.items():
+                if hashes[algorithm] != expected.lower():
+                    raise IntegrityError(f"{algorithm} mismatch: {path}")
+
+    def _store(self, path, url, headers, md5, *, move=False, checksum=None):
+        checksum = checksum or digest(path)
+        filename = Path(unquote(urlsplit(url).path)).name or "index"
+        if filename in (".", ".."):
+            filename = "index"
+        receipt = Receipt(url, checksum, path.stat().st_size, filename,
+                          datetime.now(timezone.utc).isoformat(), headers.get("etag"),
+                          headers.get("last-modified"), md5)
+        output = self.objects / object_name(checksum, filename)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        # The object may already be shared by another OpenVax tool; never rewrite valid bytes.
+        if output.is_file() and output.stat().st_size == receipt.size and digest(output) == checksum:
+            self._verified[json.dumps(file_identity(output))] = checksum
+            return receipt
+        if move:
+            share(path)
+            os.replace(path, output)
+            self._verified[json.dumps(file_identity(output))] = checksum
+            return receipt
+        fd, temporary = tempfile.mkstemp(dir=output.parent, prefix=".object-")
+        try:
+            with os.fdopen(fd, "wb") as handle, path.open("rb") as source:
+                shutil.copyfileobj(source, handle)
+            self._validate(Path(temporary), sha256=checksum, size=receipt.size)
+            share(temporary)
+            os.replace(temporary, output)
+        finally:
+            Path(temporary).unlink(missing_ok=True)
+        return receipt

osteosarc/catalog.py

@@ -0,0 +1,235 @@
+"""Reconcile all bucket objects with explicit, source-attributed metadata."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter, defaultdict
+from pathlib import PurePosixPath
+from urllib.parse import quote, unquote, urlsplit
+
+from .cache import stable_id
+from .curation import (
+    ASSAYS,
+    label_assay,
+    label_claims,
+    normalize_provider,
+    normalize_timepoint,
+    normalize_tissue,
+)
+from .errors import SchemaError
+from .models import Asset, Assets, SampleClaim
+from .urls import BUCKET, SITE, SOURCE_REPO
+
+SNAPSHOT_SOURCES = {
+    "bams": SITE + "bams/bams.json",
+    "bucket": SITE + "bucket_listing.json",
+    "variant_index": SITE + "variants/",
+    "vafs": SITE + "variants/variant_vafs_long.tsv",
+    "vaf_columns": SITE + "variants/variant_vafs_long.columns.tsv",
+    "vaccine_overlap": SITE + "data/vaccine_overlap.json",
+    "source_variants": SOURCE_REPO + "src/data/variants.json",
+    "bam_metadata": SOURCE_REPO + "scripts/data/bam-metadata-consolidated.tsv",
+    "data_page": SITE + "data/",
+}
+
+#: Dated sources behind the timeline and specimen views (about 1.7 MB).
+#: Snapshots created before these existed still open; their timeline is unavailable.
+TIMELINE_SOURCES = {
+    "events": SITE + "data/events.json",
+    "events_sheet": SOURCE_REPO + "scripts/timeline/timeline.csv",
+    "mrd": SITE + "data/mrd.json",
+    "specimens": SOURCE_REPO + "scripts/data/samples-consolidated.tsv",
+    "timepoint_summary": SOURCE_REPO + "src/data/samples.json",
+    "fastqs": SOURCE_REPO + "scripts/data/fastqs-consolidated.tsv",
+    "flow": SITE + "data/flow/manifest.json",
+    "imaging": SOURCE_REPO + "src/data/dicom-studies.json",
+    "pathology": SOURCE_REPO + "src/data/pathology-slides.json",
+    "labs": SITE + "data/lab_results.tsv",
+    "cytometry": SITE + "data/cytometry.tsv",
+}
+
+TABLE_SOURCES = {
+    "vafs": (SNAPSHOT_SOURCES["vafs"], "tsv"),
+    "vaf_columns": (SNAPSHOT_SOURCES["vaf_columns"], "tsv"),
+    "snv_top": (SITE + "oncoanalyser/tables/snv_top.tsv", "tsv"),
+    "dna_fusions": (SITE + "fusions/tables/prioritized.tsv", "tsv"),
+    "rna_fusions": (SITE + "ctat_lr_fusion/tables/lr_fusions_concordance.tsv", "tsv"),
+}
+
+
+def asset_type(key):
+    """Classify file format separately from scientific interpretation."""
+    lower = key.lower()
+    if lower.endswith((".bai", ".csi", ".crai", ".tbi", ".fai")):
+        return "index", lower.rsplit(".", 1)[-1]
+    base = lower.removesuffix(".gz").removesuffix(".bgz")
+    if base.endswith((".genes.results", ".isoforms.results")):
+        return "expression", "tsv"
+    suffix = base.rsplit(".", 1)[-1] if "." in base else ""
+    if suffix in ("bam", "cram", "sam"):
+        return "alignment", suffix
+    if suffix in ("vcf", "bcf"):
+        return "variants", suffix
+    if suffix in ("fastq", "fq"):
+        return "reads", "fastq"
+    if suffix in ("fasta", "fa", "fna", "faa"):
+        return "reference", "fasta"
+    if suffix in ("gtf", "gff", "gff3", "bed"):
+        return "annotation", suffix
+    if suffix in ("tsv", "csv", "json"):
+        return "table", suffix
+    if suffix in ("h5", "h5ad", "h5mu", "rds", "mtx", "cloupe"):
+        return "expression", suffix
+    return "other", suffix
+
+
+def bucket_url(key, base=BUCKET):
+    """Encode an exact S3 object key once; '+' and spaces remain distinct."""
+    return base.rstrip("/") + "/" + quote(key, safe="/")
+
+
+def object_key(value, base=BUCKET):
+    if value.startswith(base):
+        return unquote(value[len(base):])
+    if urlsplit(value).scheme:
+        raise SchemaError(f"Object is outside the catalog bucket: {value}")
+    return value
+
+
+def build_assets(listing, bams, metadata, vafs, path_claims=(), *, tables=None):
+    """Retain every listed object, enriching exact paths before basename matches.
+
+    Basename joins are used only when unique among alignment objects. Path
+    inferences are explicitly marked and excluded from default metadata filters.
+    The global viewer genome is retained as a claim, not assigned as assembly.
+    """
+    base = listing.get("download_base", BUCKET)
+    objects = {}
+    for row in listing["files"]:
+        if len(row) < 3 or row[0] in objects:
+            raise SchemaError("Duplicate or malformed bucket object")
+        objects[row[0]] = dict(size=int(row[1]), modified=row[2])
+    catalog, claims, extra = {}, defaultdict(list), defaultdict(dict)
+    for category in bams["categories"]:
+        for row in category["bams"]:
+            key = object_key(row["url"], bams["baseUrl"])
+            if key in catalog:
+                raise SchemaError(f"Duplicate catalog alignment: {key}")
+            catalog[key] = row
+            objects.setdefault(key, dict(size=None, modified=None))
+            assay, platform = ASSAYS.get(category["name"], (None, None))
+            match = re.match(r"(T\d+)\b", row["name"])
+            claims[key].append(SampleClaim("bams", row["name"], match[1] if match else None,
+                                           assay=label_assay(row["name"], assay), platform=platform,
+                                           tissue=normalize_tissue(row.get("tissue")),
+                                           **label_claims(row["name"])))
+            extra[key].update(catalog=row, category=category["name"],
+                              catalog_genome_assertion=bams.get("genome"))
+    for row in metadata:
+        if not row.get("s3_path"):
+            continue
+        key = object_key(row["s3_path"], base)
+        objects.setdefault(key, dict(size=None, modified=None))
+        assay, platform = ASSAYS.get(row.get("assay"), (None, None))
+        claims[key].append(SampleClaim("bam_metadata", row["display_name"], normalize_timepoint(row.get("timepoint")),
+                                       row.get("sample_date") or None, assay, platform,
+                                       normalize_tissue(row.get("tissue")), normalize_provider(row.get("provider"))))
+        extra[key].setdefault("metadata_rows", []).append(row)
+    counts = Counter(PurePosixPath(key).name for key in objects if asset_type(key)[0] == "alignment")
+    by_basename = defaultdict(set)
+    for row in vafs:
+        by_basename[row["bam_file"]].add(tuple(row.get(k, "") for k in
+            ("sample_label", "timepoint", "sample_date", "assay_type", "tissue", "data_source")))
+    by_path = defaultdict(list)
+    for prefix, claim in path_claims:
+        by_path[prefix.rstrip("/")].append(claim)
+    assets = []
+    for key, object_metadata in objects.items():
+        kind, format = asset_type(key)
+        info = dict(extra.get(key, {}))
+        records = list(claims.get(key, ()))
+        # The most specific data-page path wins: a file's own row overrides the
+        # row for its directory, which can also hold other assays' files.
+        parts = key.split("/")
+        for depth in range(len(parts), 0, -1):
+            if "/".join(parts[:depth]) in by_path:
+                records.extend(by_path["/".join(parts[:depth])])
+                break
+        if kind == "alignment":
+            basename = PurePosixPath(key).name
+            if counts[basename] == 1:
+                for label, timepoint, date, assay_name, tissue, provider in sorted(by_basename[basename]):
+                    assay, platform = ASSAYS.get(assay_name, (None, None))
+                    records.append(SampleClaim("vafs", label, normalize_timepoint(timepoint), date or None,
+                                               assay, platform, normalize_tissue(tissue), normalize_provider(provider)))
+            elif by_basename[basename]:
+                info["ambiguous_vaf_basename"] = basename
+        # This inference is useful for discovery, but never establishes identity.
+        points = sorted(set(re.findall(r"(?:^|[/_ .-])(T[0-3])(?=[/_ .-]|$)", key)))
+        libraries = sorted(set(re.findall(r"\b(?:BG\d{6}|SARC\d{4}|TL-\d{2}-[A-Z0-9]+)\b", key)))
+        if kind != "other":
+            for point in points:
+                records.append(SampleClaim("bucket_path", key, timepoint=point, basis="inferred"))
+            for library in libraries:
+                records.append(SampleClaim("bucket_path", key, library=library, basis="inferred"))
+        suffixes = [key + ".bai", key[:-4] + ".bai", key + ".csi"] if format == "bam" else (
+            [key + ".crai", key[:-5] + ".crai", key + ".csi"] if format == "cram" else
+            [key + ".tbi", key + ".csi"] if format in ("vcf", "bcf") else [])
+        indexes = tuple(bucket_url(k, base) for k in suffixes if k in objects)
+        url = bucket_url(key, base)
+        assets.append(Asset(stable_id(url), key, url, kind, format, index_urls=indexes,
+                            claims=tuple(records), metadata=info, **object_metadata))
+    for name, (url, format) in (tables or TABLE_SOURCES).items():
+        assets.append(Asset(stable_id(url), "site/" + name, url, "table", format,
+                            metadata={"resource": name}))
+    return Assets(assets)
+
+
+def data_page_rows(html):
+    """Yield (section context, {column: text}) for data-page rows with a bucket path."""
+    from bs4 import BeautifulSoup
+    soup = BeautifulSoup(html, "html.parser")
+    headings = {}
+    for element in soup.find_all(["h2", "h3", "h4", "table"]):
+        if element.name != "table":
+            level = int(element.name[1])
+            headings = {k: v for k, v in headings.items() if k < level}
+            headings[level] = element.get_text(" ", strip=True)
+            continue
+        context = " / ".join(headings.values())
+        headers = [c.get_text(" ", strip=True) for c in element.select("thead th")]
+        if not headers:
+            headers = [c.get_text(" ", strip=True) for c in element.select("tr:first-child th")]
+        for row in element.select("tr"):
+            cells = row.find_all("td", recursive=False)
+            if len(cells) != len(headers):
+                continue
+            values = dict(zip(headers, (c.get_text(" ", strip=True) for c in cells)))
+            if "Bucket Path" in values:
+                yield context, values
+
+
+def parse_data_paths(html):
+    """Extract the data page's explicit path-to-sample claims, including FASTQs.
+
+    Assays/platforms come from section headings, tissues/providers from cells.
+    Composite tissues and timepoints remain unresolved rather than guessed.
+    """
+    result = []
+    for context, values in data_page_rows(html):
+        title = context.lower()
+        assay = ("wgs" if "whole genome" in title or re.search(r"\bwgs\b", title) else
+                 "wes" if "whole exome" in title or re.search(r"\bwes\b", title) else
+                 "scrna-seq" if any(x in title for x in ("single cell", "single-cell")) else
+                 "rna-seq" if "bulk rna" in title else None)
+        platform = ("ont" if "nanopore" in title else "pacbio" if "pacbio" in title else
+                    "illumina" if "illumina" in title else None)
+        points = set(re.findall(r"\bT[0-3]\b", values.get("Timepoint", "")))
+        tissue = normalize_tissue(values.get("Tissue"))
+        label = " | ".join(v for k, v in values.items() if k not in ("Bucket Path", "Size", "Files"))
+        result.append((values["Bucket Path"].strip("`"), SampleClaim(
+            "data_page", context + " / " + label,
+            timepoint=next(iter(points)) if len(points) == 1 else None,
+            assay=assay, platform=platform, tissue=tissue,
+            provider=normalize_provider(values.get("Provider")))))
+    return tuple(result)