# Building a Sample Annotation Template for Large-Scale Genomics By the end of this article you will be able to design a sample annotation template for a sequencing project with hundreds to hundreds of thousands of samples, write a machine-readable data dictionary for it, validate filled-in copies with a short Python script, catch the spreadsheet and encoding errors that silently corrupt genomic metadata, and hand a pipeline-ready sample sheet to your analysis workflow. You will need Python 3.9 or later with pandas installed, a plain-text editor, the `md5sum` or `md5` checksum utility, and optionally csvkit for spreadsheet conversions. Everything runs on a laptop. No cluster, database, or paid tool is required. A sample annotation template is a fixed table structure, usually a CSV or TSV file with one row per biological sample, that records what each sample is, where it came from, how it was processed, and where its raw data lives. In a small pilot you can reconstruct this information from Slack messages and notebook pages. At scale you cannot. Public resources show what disciplined metadata looks like when it is done well. [Gene Expression](/blog/guides/gene-expression) Nebulas 2.0 curates standardized transcriptomic profiles and manually reviewed metadata for 102,679 samples across 668 datasets and 100 species, and its usefulness rests directly on that annotation layer being consistent [1]. The workflow below shows you how to build the same discipline into your own project from day one. ## Why a Written Template Beats Ad Hoc Spreadsheets Every large genomics project eventually hits the same wall. The bioinformatician who needs to run differential expression across 300 tumors asks which samples are treatment and which are control, and the answer lives in four different Excel files, two email threads, and one LIMS export with inconsistent column names. Rebuilding that mapping takes days and introduces errors that surface months later as unexplainable batch effects. A shared annotation template fixes this at the source. It gives you four things: 1. **A single place where sample facts live**, so analysts stop guessing and start joining. 2. **Machine-readable metadata**, so sample selection, batch detection, and quality-control stratification become scriptable rather than manual. 3. **Traceability**, so every derived result can be traced back to a physical specimen, a collection event, and a consent decision. Large integration efforts depend on exactly this property. IsoMatch, a framework that merges transcript catalogs across 163 ENCODE samples and classified 7.9 million transcript models with peak memory under 1.1 GB, explicitly preserves source-file and original-transcript traceability so every merged model can be traced back to its contributing inputs [2]. Your sample table is the upstream anchor that makes that kind of traceability possible. 4. **A doorway to standards.** Biobank-grade annotation has mature normative frameworks you can borrow field definitions from, including the ISBER Best Practices (fifth edition, 2023), the revised NCI Best Practices (2026), the Standard PREanalytical Code (SPREC) version 4.0, MIABIS Core 3.0, and ISO 20387, the accreditation standard for biobanks [3]. You do not need accreditation to benefit. You need the field definitions. The cost of skipping this step compounds. Annotation problems are the most common reason a well-sequenced dataset produces a poorly interpretable analysis. ## Design Principles Before You Open a Spreadsheet Five principles separate templates that survive a multi-year project from templates that get rebuilt every six months. ### One row, one sample, and a definition of "sample" Decide before writing the header whether a row is a specimen, an extraction, a library, or a sequencing run. For most RNA-seq and WGS projects the right granularity is one row per sequencing library, because that is the unit pipelines consume. If a subject contributes two biopsies sequenced twice, that subject occupies four rows, and the relationships are expressed through identifier columns rather than by splitting tables. Mixing granularities in one table is the leading cause of duplicate-sample bugs downstream. ### Stable, machine-safe identifiers Every sample gets an identifier matching a fixed pattern, for example `^[A-Za-z0-9_\-]+$`, generated centrally and never reused. Human-typed names like `patient 3 (second draw!)` break every parser they touch. Keep a separate `subject_id` column so repeated sampling of one individual is visible without breaking sample-level uniqueness. ### Controlled vocabularies for anything an analyst will group by Columns such as `tissue`, `condition`, `library_prep`, and `sequencing_platform` must draw values from a closed list you publish alongside the template. Free text guarantees that "kidney", "Kidney", "kidney (cortex)", and "KIDNEY " become four groups. For biospecimen and pre-analytical variables, SPREC version 4.0 provides a recognized coding scheme for sample type, collection method, and processing steps [3]. For sample-to-donor linkage in biobank contexts, MIABIS Core 3.0 defines the shared attribute model [3]. Even a homemade five-value vocabulary beats free text, as long as the vocabulary is written down and enforced. ### A data dictionary, not tribal knowledge The data dictionary is a second file, one row per column of the template, giving the column name, allowed type, allowed values, whether the field is required, and a one-line definition. Anyone joining the project reads the dictionary instead of asking you what `batch_code` means. ### An explicit missing-value convention Pick one sentinel, write it in the dictionary, and use it everywhere. The convention `NA` (uppercase, no quotes) is the least surprising for R and pandas users alike. An empty cell, a hyphen, and the string "unknown" should not coexist, because each downstream tool treats them differently. ## Choosing a Sample Annotation Template Genomics Format ![Decision path asking about shared catalogs, nested fields, and spreadsheet editing, ending at UTF-8 TSV stored in git as the canonical format.](/article-images/illustrations/sample-annotation-template-genomics-format-choice.webp) The question of the best sample annotation template genomics format has a boring answer with important edges. Store the canonical copy as plain-text delimited data, version it in git, and treat spreadsheets as editing views rather than storage. The comparison below summarizes the tradeoffs. | Format | Best for | Main risks | Notes | |--|--|--|--| | TSV or CSV (UTF-8) | Canonical, versioned storage, pipeline input | Manual edits with stray delimiters | Universal tooling, diff-friendly in git | | Excel or Google Sheets | Data entry and visual review | Date autocorruption, type coercion, encoding loss on export | Fine as an entry layer, never as the archive | | JSON or YAML | Config-like metadata, small sample counts, pipeline configs | Hard to eyeball for 1,000 rows | Good for per-sample blocks with nested fields | | Relational database | Very large or multi-project catalogs | Overhead, access barriers for collaborators | Worth it when multiple studies share one catalog | | HDF5 or Parquet | Analytical snapshots of annotation | Not human-editable | Derived view, regenerate from the TSV | Two source-grounded observations reinforce this. LDblockR unified LD analysis across VCF, HapMap, and PLINK formats and framed its contribution as workflow integration and interoperability rather than a new estimator, which reflects a general truth: format heterogeneity is where integration effort goes to die [4]. And the phage bioinformatics literature has documented ecosystem-level fragility when shared upstream dependencies change, a reminder that your annotation layer should not depend on any single tool's private format [5]. If you must accept Excel from collaborators, convert and verify immediately: ```bash # Convert an Excel workbook to TSV (csvkit) in2csv SAMPLESHEET.xlsx | csvformat -T > SAMPLESHEET.tsv # Then run your validation script before anyone touches the data python validate_template.py SAMPLESHEET.tsv ``` ## Building the Template: A Numbered Walkthrough ![Seven-step flow from drafting columns through dictionary, frozen template, entry rules, validation, checksum check, and provenance.](/article-images/illustrations/sample-annotation-template-genomics-template-walkthrough.webp) This walkthrough builds a working template for a bulk RNA-seq cohort of 240 samples. The same structure transfers to WGS, metagenomics, or single-cell projects with different vocabulary lists. ### Step 1: Draft the column set Start with the minimum columns an analyst needs to reproduce a result and find a file. For this example: | Column | Type | Required | Rule | Example | |--|--|--|--|--| | sample_id | string | yes | unique, regex `[A-Za-z0-9_\-]+` | SPT001 | | subject_id | string | yes | may repeat across samples | SUB014 | | biospecimen_type | enum | yes | closed list | fresh_frozen_tissue | | collection_date | date | yes | ISO 8601, `YYYY-MM-DD` | 2025-03-15 | | tissue | enum | yes | closed list | kidney | | condition | enum | yes | closed list | case | | timepoint | string | yes | controlled token | baseline | | batch_code | string | yes | matches lab log | B2025A | | library_prep | enum | yes | closed list | polyA_stranded | | sequencing_platform | enum | yes | closed list | Illumina_NovaSeq | | read_length_bp | integer | yes | greater than 0 | 150 | | run_accession | string | yes | stable run identifier | RUN000123 | | fastq_path_r1 | path | yes | relative path, must exist | data/raw/SPT001_R1.fastq.gz | | fastq_path_r2 | path | yes | must exist for paired-end | data/raw/SPT001_R2.fastq.gz | | md5_r1 | string | yes | 32 lowercase hex | 3f5a8c... | | consent_group | enum | yes | closed list | general_research | Two design points deserve emphasis. `collection_date` in ISO 8601 (`YYYY-MM-DD`) sorts correctly as text and parses unambiguously in every language. And file paths in the table are relative to a declared project root, recorded in a `README`, so the table survives a move to new storage without edits. ### Step 2: Write the data dictionary Create `dictionary.yaml` next to the template. This file is what your validator reads, so the rules are enforced rather than aspirational. ```yaml template_version: "1.2.0" project_root: "data" columns: sample_id: type: string required: true unique: true pattern: "^[A-Za-z0-9_\\-]+$" subject_id: type: string required: true biospecimen_type: type: enum required: true values: [fresh_frozen_tissue, ffpe_block, blood, cell_line] collection_date: type: date required: true format: "%Y-%m-%d" tissue: type: enum required: true values: [kidney, liver, lung, heart, brain] condition: type: enum required: true values: [case, control] timepoint: type: string required: true values: [baseline, week_12, week_52] batch_code: type: string required: true library_prep: type: enum required: true values: [polyA_stranded, ribo_deplete, total_stranded] sequencing_platform: type: enum required: true values: [Illumina_NovaSeq, Illumina_NextSeq, PacBio_HiFi] read_length_bp: type: integer required: true minimum: 20 run_accession: type: string required: true fastq_path_r1: type: path required: true fastq_path_r2: type: path required: true md5_r1: type: string required: true pattern: "^[a-f0-9]{32}$" consent_group: type: enum required: true values: [general_research, disease_specific, withdrawn] ``` ### Step 3: Freeze the blank template Create the header and two example rows as `SAMPLESHEET_TEMPLATE.tsv`. Example rows are marked with `sample_id` values beginning with `EXAMPLE_` so validators and analysts can recognize and exclude them. ```text sample_id subject_id biospecimen_type collection_date tissue condition timepoint batch_code library_prep sequencing_platform read_length_bp run_accession fastq_path_r1 fastq_path_r2 md5_r1 consent_group SPT001 SUB014 fresh_frozen_tissue 2025-03-15 kidney case baseline B2025A polyA_stranded Illumina_NovaSeq 150 RUN000123 data/raw/SPT001_R1.fastq.gz data/raw/SPT001_R2.fastq.gz d41d8cd98f00b204e9800998ecf8427e general_research SPT002 SUB014 fresh_frozen_tissue 2025-03-15 kidney case week_12 B2025A polyA_stranded Illumina_NovaSeq 150 RUN000124 data/raw/SPT002_R1.fastq.gz data/raw/SPT002_R2.fastq.gz 0bf7d2a04e2f0e1a9d3c8c7e6b5a4938 general_research ``` Commit this file to git and tag it. The combination of template version `1.2.0` and the git tag is what lets you answer, a year from now, exactly which column definitions a given result depended on. ### Step 4: Fill it in under entry rules Distribute the blank template with three rules stated in the accompanying README: 1. Enter values only from the allowed lists in the dictionary. If a needed value is absent, request an addition through the project lead rather than improvising a synonym. 2. Never delete or reorder columns. Additions go at the end and require a version bump. 3. Dates are typed as `YYYY-MM-DD` as text. In Excel, format the column as Text before pasting, because Excel will otherwise reinterpret entries according to its locale. That last rule addresses a documented failure mode: spreadsheet applications autoconvert certain text strings into dates, which has historically mangled gene symbols and identifiers in shared datasets. Keeping the canonical copy in TSV sidesteps the entire class of problem. ### Step 5: Validate with a script Write `validate_template.py` and run it on every submitted sheet. The script below reads the YAML dictionary, checks header order, uniqueness, patterns, enums, dates, file existence, and checksum integrity, and exits nonzero on any error so it can gate an automated pipeline. ```python #!/usr/bin/env python3 """Validate a sample annotation TSV against dictionary.yaml.""" import sys, re, hashlib, datetime from pathlib import Path import yaml import pandas as pd def main(tsv_path, dict_path="dictionary.yaml"): spec = yaml.safe_load(Path(dict_path).read_text()) cols_spec = spec["columns"] expected_cols = list(cols_spec.keys()) root = Path(spec.get("project_root", ".")) try: df = pd.read_csv(tsv_path, sep="\t", dtype=str, keep_default_na=False, encoding="utf-8-sig") except UnicodeDecodeError as e: print(f"FAIL encoding: {e}") print("Fix: save the file as UTF-8, or run " "iconv -f WINDOWS-1252 -t UTF-8 on it.") sys.exit(1) except pd.errors.ParserError as e: print(f"FAIL parse: {e}") print("Fix: check for stray tab characters or unquoted fields.") sys.exit(1) errors = [] if list(df.columns) != expected_cols: errors.append(f"header mismatch: expected {len(expected_cols)} " f"columns in fixed order, found {list(df.columns)}") seen = {} for i, row in df.iterrows(): line = i + 2 # 1-based file line, header is line 1 sid = row.get("sample_id", "") if sid.startswith("EXAMPLE_"): continue if sid in seen: errors.append(f"duplicate sample_id: {sid} appears in rows " f"{seen[sid]} and {line}") else: seen[sid] = line for col, rule in cols_spec.items(): val = str(row.get(col, "")).strip() if rule.get("required") and val == "": errors.append(f"missing required value: row {line} " f"column {col} is empty") continue if val == "": continue if "values" in rule and val not in rule["values"]: errors.append(f"controlled vocabulary: row {line} column " f"{col} value '{val}' not in {rule['values']}") if "pattern" in rule and not re.match(rule["pattern"], val): errors.append(f"pattern mismatch: row {line} column {col} " f"value '{val}' violates {rule['pattern']}") if rule.get("type") == "date": try: datetime.datetime.strptime(val, rule.get("format", "%Y-%m-%d")) except ValueError: errors.append(f"date format: row {line} column {col} " f"value '{val}' is not ISO 8601 YYYY-MM-DD") for col in ("fastq_path_r1", "fastq_path_r2"): val = str(row.get(col, "")).strip() if val and not (root / val).is_file(): errors.append(f"file not found: row {line} {col} = {val}") p1 = str(row.get("fastq_path_r1", "")).strip() md5_stored = str(row.get("md5_r1", "")).strip() f1 = root / p1 if p1 else None if f1 and f1.is_file() and re.fullmatch(r"[a-f0-9]{32}", md5_stored): h = hashlib.md5() with open(f1, "rb") as fh: for chunk in iter(lambda: fh.read(1024 * 1024), b""): h.update(chunk) if h.hexdigest() != md5_stored: errors.append(f"checksum mismatch: row {line} {col} file " f"{p1} hashes to {h.hexdigest()}, " f"sheet says {md5_stored}") n = len(df) if errors: print(f"FAILED: {n} rows, {len(errors)} errors") for e in errors[:20]: print(" " + e) if len(errors) > 20: print(f" ... and {len(errors) - 20} more") sys.exit(1) else: print(f"OK: {n} rows passed all checks") sys.exit(0) if __name__ == "__main__": main(sys.argv[2], sys.argv[5] if len(sys.argv) > 2 else "dictionary.yaml") ``` Run it: ```bash python validate_template.py SAMPLESHEET.tsv ``` Expected output on a clean sheet: ```text OK: 240 rows passed all checks ``` Expected output on a sheet with problems: ```text FAILED: 240 rows, 7 errors duplicate sample_id: SPT001 appears in rows 2 and 3 date format: row 7 column collection_date value '03/15/2025' is not ISO 8601 YYYY-MM-DD controlled vocabulary: row 12 column tissue value 'kidny' not in ['kidney', 'liver', 'lung', 'heart', 'brain'] missing required value: row 18 column library_prep is empty file not found: row 9 fastq_path_r1 = data/raw/SPT009_R1.fastq.gz checksum mismatch: row 9 fastq_path_r1 file data/raw/SPT009_R1.fastq.gz hashes to 8f14e45fceea167a5a36dedd4bea2543, sheet says d41d8cd98f00b204e9800998ecf8427e pattern mismatch: row 31 column sample_id value 'SPT 031' violates ^[A-Za-z0-9_\-]+$ ``` Exit code 1 lets you wire this into continuous integration so a merged pull request containing a broken sheet fails loudly instead of failing silently three weeks later. ### Step 6: Verify file integrity independently Checksums deserve a second, independent check outside the script, because the checksum column itself can be mistyped. ```bash # Recompute all checksums from disk into a sidecar file md5sum data/raw/*.fastq.gz > data/raw/md5sums.txt # Compare against the sheet md5sum -c data/raw/md5sums.txt ``` Expected output for intact files: ```text data/raw/SPT001_R1.fastq.gz: OK data/raw/SPT001_R2.fastq.gz: OK data/raw/SPT002_R1.fastq.gz: OK data/raw/SPT002_R2.fastq.gz: OK ``` A reported `FAILED open or read` means the file is missing at the recorded path, and a reported `FAILED md5 checksum` means the bytes differ from what was registered, which after a network transfer usually indicates a corrupted or truncated copy. Re-transfer rather than re-hashing your way around it. ### Step 7: Register provenance and version Add a `PROVENANCE.md` beside the template recording the template version, the git commit of the dictionary, who filled in which batch, and the date of each validation run. When your project later feeds an integration effort, this registry is what connects your rows to everything downstream. It is the same principle that lets a tool like IsoMatch trace every merged transcript model back to its source GTF and contributing input across 163 sample-level catalogs [2]. Traceability is a property you build in at the annotation layer, not something you can retrofit onto a pile of files. ## Common Errors with Exact Messages and Fixes These are the errors that account for most annotation-table debugging time, with the messages you will actually see. **Stray delimiter.** A cell contains a tab or an extra column gets pasted in. pandas reports: ```text pandas.errors.ParserError: Error tokenizing data. C error: Expected 16 fields in line 42, saw 17 ``` Locate the line with a quick shell check: ```bash awk -F'\t' 'NR>1 && NF!=16 {print FILENAME, "line", NR, "has", NF, "fields"}' SAMPLESHEET.tsv ``` Fix the offending cell in a plain-text editor, not Excel, then re-run the validator. **Windows encoding.** A collaborator edits the file in an older Windows tool and you get: ```text UnicodeDecodeError: 'utf-8' codec can't decode byte 0x96 in position 412: invalid start byte ``` Convert before validating: `iconv -f WINDOWS-1252 -t UTF-8 badfile.tsv > SAMPLESHEET.tsv`. Better, ask collaborators to edit the canonical UTF-8 copy in a plain-text editor or a modern spreadsheet that writes UTF-8 by default. **Invisible byte-order mark.** A UTF-8 file exported from Windows carries a leading BOM, so the first column reads as `\ufeffsample_id` and lookups fail with: ```text KeyError: 'sample_id' ``` The validator above already guards against this with `encoding="utf-8-sig"`. For ad hoc inspection, `sed -i '1s/^\xEF\xBB\xBF//' file.tsv` removes it. **Excel type coercion.** Gene symbols like `SEPT1` become dates, and identifiers with leading zeros lose them, when a TSV is opened and re-saved in Excel. The fixes are structural: import identifier columns as Text, and keep the canonical file as TSV so Excel is never the storage layer. **Checksum mismatch after transfer.** `md5sum -c` reports `FAILED md5 checksum` for files that downloaded fine by size. Usually the transfer happened in text mode or through a tool that altered line endings. Re-transfer in binary mode and compare against the original hash, not a freshly computed one from the same bad copy. **Silent trailing whitespace.** `" control"` and `"control"` are different strings to pandas but identical to a human. The validator strips values before comparing, and the closed-vocabulary check catches the residue. If you see the vocabulary error for a value that looks correct, suspect trailing whitespace first. ## Connecting the Template to Bioinformatics Data Management and Storage The template earns its keep once it is wired into bioinformatics [data management](/blog/guides/data-management-basics-principles-processes-and-best-practices) rather than sitting in a shared drive. Three connections matter. **Pipelines consume a derived sample sheet.** Most modern workflow systems read a simple sample sheet. For a paired-end RNA-seq workflow the standard shape is: ```csv sample,fastq_1,fastq_2 SPT001,data/raw/SPT001_R1.fastq.gz,data/raw/SPT001_R2.fastq.gz SPT002,data/raw/SPT002_R1.fastq.gz,data/raw/SPT002_R2.fastq.gz ``` Generate this sheet from the annotation template with a five-line script instead of maintaining it by hand, so there is exactly one source of truth. Never let an analyst hand-edit the derived sheet, because the edit will not flow back to the template and the divergence becomes next quarter's mystery. **Storage layout mirrors the template.** A predictable layout for genomics data storage makes the path columns meaningful and lets you reconstruct any project from the table alone: ```text project_root/ SAMPLESHEET_TEMPLATE.tsv dictionary.yaml PROVENANCE.md data/ raw/SPT001_R1.fastq.gz ... checksums/md5sums.txt results/SPT001/ ... docs/README.md ``` Permissions follow the consent column. Samples marked `withdrawn` in `consent_group` are excluded from derived outputs by script, not by memory, which is the only way to honor a withdrawal reliably across reruns. Biobanking guidance is explicit that governance decisions attached to specimens must be enforced by the systems holding them, which is one of the practical threads running through the current international biobanking standards [3]. **External identifiers get recorded, not invented.** If samples map to public archives or internal biobank stock numbers, store those identifiers in their own columns. Cross-referencing pays off when you later want to integrate external resources. EpuDB, for example, links 70 RNA-seq samples from six BioProjects into a unified functional-genomics resource precisely by joining sample-level records across sources rather than treating each dataset as an island [6]. ## Quality Control and Aggregation on Top of the Template Once the table is valid, use it as the stratification backbone for quality control. Batch effects, library-preparation effects, and tissue effects are only visible if your QC figures can be grouped by the annotation columns, which is the whole reason those columns are controlled vocabularies. Aggregated QC also catches annotation-level problems that per-sample checks miss. The metagenomics literature illustrates the scale problem concretely: standard annotation tools emit 10 to 14 output files per assembled bin, which makes manual review infeasible, and dedicated aggregation is needed to summarize results across an entire dataset. The annoreport tool processed 206 metagenome-assembled genomes and summarized 603,799 predicted coding sequences, finding a 47.1 percent annotation rate, in a single interactive report [7]. The lesson generalizes directly to sample annotation. If your quality-control summary cannot be produced by one command over the whole table, your table design, not your effort, is the constraint. ## Common Mistakes and Limitations - **Defining "sample" inconsistently between the wet lab and the pipeline.** If the lab counts a row per tube and the pipeline counts a row per library, duplicates are guaranteed. Settle the unit of annotation in writing before data collection starts. - **Letting the vocabulary drift.** A new analyst adds `Tumor-NOS` alongside `case` because the closed list felt restrictive. Every vocabulary addition should require a dictionary version bump and a validator update, announced to everyone whose analyses depend on the grouping. - **Storing the canonical copy in a spreadsheet.** Excel autocorruption, locale-dependent dates, and silent re-encoding make spreadsheets unfit as the system of record. Edit there if you must, but commit the TSV. - **Skipping checksum verification until a failure.** Verify checksums at ingest, before analysis, and before archival. Discovering corruption after a year of analysis means repeating the year. - **Assuming the blank template enforces itself.** A template file enforces nothing. Only the validator, run automatically on every submission, enforces the rules. Pair them and treat any sheet that has not passed validation as nonexistent. - **Underestimating linkage metadata.** The hardest columns to fill are the ones connecting samples to consent, processing history, and batch. SPREC version 4.0 and MIABIS Core 3.0 exist because these pre-analytical and linkage variables determine scientific value, and the biobanking field has spent decades formalizing them [3]. Borrow their definitions rather than inventing your own. - **Expecting one template to fit every assay forever.** Design for change by versioning the dictionary and appending columns rather than mutating existing ones. Tool ecosystems shift underneath you, and reviews of computational fields increasingly flag dependency fragility as a systemic risk [5]. A versioned, plain-text annotation layer is your buffer against that. - **A general limitation of the approach.** A template records what was entered. Data-quality problems at the level of the underlying datasets, such as sparse or unevenly sampled metadata in public repositories, limit what any annotation layer can fix, a constraint that applies across genomics subfields [8]. For clinical interpretation of any individual specimen, consult the relevant clinical service or qualified professional rather than relying on research annotations alone. ## Frequently Asked Questions ### What is a sample annotation template in genomics? It is a fixed, machine-readable table with one row per sample or sequencing library that records specimen identity, origin, processing, consent, and data-file locations. It serves as the single source of truth that pipelines, quality-control scripts, and analysts all read from. ### Which sample annotation template genomics format should I use? Use UTF-8 encoded TSV or CSV as the canonical format, versioned in git. Use spreadsheets only for data entry, and JSON or YAML for per-sample nested metadata. Relational databases become worthwhile when many projects share one catalog. ### What is a good sample annotation template genomics example to start from? The 16-column RNA-seq template in this article, with its `dictionary.yaml`, is a complete starting example. Keep the required core small, meaning identifiers, specimen facts, batch, library, file paths, and consent, and extend it per project. ### Is there a free sample annotation template genomics template I can copy? Yes. The blank template, the data dictionary, and the validation script in this article are all plain text you can copy directly into your repository and adapt. Public standards such as SPREC 4.0 and MIABIS Core 3.0 provide additional field definitions you can borrow at no cost. ### How do I handle missing data in the template? Pick one sentinel value, most commonly `NA`, declare it in the data dictionary, and require it in place of empty cells for optional fields. Required fields must never be missing, and the validator enforces that distinction. ### How many columns should the template have? Fewer than you think, typically 15 to 30 for a sequencing study. Every column should have a named owner, a defined type, and an analyst who will use it. Columns nobody consumes get abandoned and become sources of drift. ### How do I connect the template to my analysis pipeline? Generate a pipeline-specific sample sheet from the template with a script, and never edit the derived sheet by hand. For paired-end short-read workflows, a three-column CSV of sample and fastq paths is the common input shape. ### How do I keep the template consistent across multiple projects? Maintain one shared core dictionary with project-specific extensions appended as new columns, bump the version on every change, and run the same validator across all projects in continuous integration. A shared validator catches drift that individual project teams cannot see. ## Sources 1. [Gene Expression Nebulas 2.0: an updated resource of gene expression profiles by incorporating more datasets, annotations, and functionalities.](https://pubmed.ncbi.nlm.nih.gov/43006148/) 2. [IsoMatch enables population-scale transcript integration and reveals reference-dependent isoform novelty.](https://pubmed.ncbi.nlm.nih.gov/42999141/) 3. [From Donor to Discovery and Diagnosis: A Comprehensive 2026 Review of International Biobanking Guidelines Underpinning Molecular Pathology-Driven Cancer Diagnostics, with a Practical Roadmap for Establishing a New Biobank.](https://pubmed.ncbi.nlm.nih.gov/42794940/) 4. [LDblockR: a cross-platform R toolkit for multi-format linkage disequilibrium analysis and integrated regional genomics visualization.](https://pubmed.ncbi.nlm.nih.gov/43005392/) 5. [Phage bioinformatics tools: a review of computational approaches for bacteriophage research.](https://pubmed.ncbi.nlm.nih.gov/42743975/) 6. [EpuDB: an integrated functional genomics database and REST API for Epimedium pubescens.](https://pubmed.ncbi.nlm.nih.gov/43011377/) 7. [annoreport: an interactive tool for metagenome annotation.](https://pubmed.ncbi.nlm.nih.gov/42763764/) 8. [AI-enabled viral genomics: from virus discovery to host prediction and emerging variant forecasting.](https://pubmed.ncbi.nlm.nih.gov/42632361/)