From raw data to a traceable PDF report

A genomic analysis often ends with a file that looks orderly. Tables line up, findings have headings, and references sit at the back. The harder quality question starts much earlier: can each statement still be traced to its input, the tool that produced it, and the technical limitations that applied at the time?

Maintaining that connection is harder than rendering a PDF. Between a raw dataset and the final report sit file formats, reference builds, quality checks, and several analysis domains that should not be mixed. If one of those transitions remains implicit, the result may look complete while being difficult to audit later.

Genome therefore does not treat the report as a polished afterthought to a pipeline. It is the readable end of a documented run. This article follows the path from FASTQ, BAM, or CRAM to PDF and looks at the information that must survive along the way.

The report begins with the input

FASTQ contains the DNA fragments read by a sequencer and the base quality assigned to each position. In paired-end data, R1 and R2 belong together. Swapping one mate or using an incomplete pair can compromise every step that follows. Genome therefore links selected inputs to a sample and a particular run instead of relying on a descriptive filename alone.

BAM and CRAM files have already been aligned. They contain sequence reads together with positions on a reference genome. The main file is still not sufficient by itself. Regional access commonly uses a BAI or CSI index for BAM and a CRAI index for CRAM. CRAM also has an especially strong dependency on the correct reference because parts of its sequence information are stored relative to that reference. A file can be technically readable and still be incompatible with the reference expected by the next tool.

Genome starts selection of the main formats with file type and extension. The relevant workflow step then checks the expected headers, indexes, and result structures. BAM and CRAM therefore have different companion requirements from specialised report inputs. The filename participates in selection, while the checks required by the next step provide the technical validation.

The Wiki introduction to WGS, SNP arrays, and exome sequencing explains how the major input types differ. For reporting, the central requirement is that input identity stays stable throughout the run. An artefact created later must lead back to this exact input, not merely to a directory that may now hold other files as well.

Reference and technical quality

FASTQ does not turn directly into a medical finding. Reads are first checked, cleaned when appropriate, and aligned to a reference. Genome orchestrates the required bioinformatics tools locally on the Mac. Intermediate data stays on the device. The aligned reads become a sorted and indexed BAM that specialised analyses can query efficiently.

The reference is not interchangeable background material. GRCh37 and GRCh38 use different coordinates. Even files described with the same broad build label may differ in extra contigs or masking. A traceable run therefore records more than the string “GRCh38”. It binds the actual reference and its verified identity to the run.

Before interpretation, the workflow also needs to establish whether the relevant data is sufficiently complete and consistent. Coverage summaries describe how deeply regions were read. Other checks can flag possible contamination or an unexpected sample identity. If a quality signal is absent, that is not the same as a passed check. Genome does not silently convert missing quality evidence into a green result.

This matters in practice. A variant record with weak coverage may be formally present but does not carry the same support as a stable call. The report needs to preserve that difference. It should state not only what was found, but also the technical basis on which it was found.

Analysis domains stay separate

Alignment and quality control do not feed one universal “genome test”. Different questions require different tools, references, and interpretation rules. Genome keeps those domains separate on purpose.

HLA typing is not the same process as small variant calling. KIR analysis uses its own gene models. Pharmacogenomics brings variants together into genotypes, haplotypes, or star alleles. Repeat expansion analysis examines lengths in repetitive regions that ordinary SNP tables do not represent well. Polygenic scores require both variant data and a defined score model with a documented source.

The claim boundaries differ too. An HLA allele may have a supported risk context, but it is not a diagnosis. EBV sequence traces describe technical coverage or sequence evidence, not an infection. A pharmacogenomic result must not drift unnoticed into a general medical genomics report. Keeping the domains apart prevents a correctly calculated observation from being interpreted too broadly in the wrong setting.

Genome manages tools such as HLA*LA, T1K, Aldy, and ExpansionHunter locally and records their role in the workflow. The tool name alone is not enough. The specific version, its reference, the input, and the run status all matter. Together they turn a result file into an auditable artefact.

The manifest connects the run

A pipeline produces many files: cleaned reads, alignments, indexes, quality summaries, result tables, and reports. A directory containing all of them is not yet provenance. Filenames can change, older results can remain in the same output directory, and a cancelled run can leave incomplete artefacts behind.

A run manifest makes the relationships explicit. It records which inputs and parameters belonged to the run, which tools and references were used, and which outputs were newly created. Where identities are available, Genome ties artefacts to file size and SHA-256. A later check can then determine whether a file is still the same file described by the run. Missing provenance is neither filled in nor guessed. The report then remains explicitly labelled as an unverified Research Use Only export.

The manifest matters when resuming interrupted work as well. An existing filename is not a sufficient checkpoint. Before a step is reused, its input, tool, reference, and relevant parameters have to match the saved state. A mismatch must cause the step to run again or stop in a controlled way. Otherwise, a new report could combine old intermediate data with a new configuration.

Most of this stays in the background during an ordinary run. It becomes useful when somebody asks why a new report differs from an older one. Was a reference updated? Did the quality file really come from this run? A manifest makes those questions answerable without reconstructing the entire process from memory.

Why PDF-first is more than a file format

Genome produces reports PDF-first. PDF itself does not guarantee scientific quality. Its value here is a stable, readable artefact that keeps the content, references, navigation, and recorded generation state together.

A traceable report connects a finding with its context. It names the data basis, describes the method, and shows quality information where readers need it. Literature references lead back to the underlying sources. Limitations are part of the statement rather than a detached legal note. The report language is selected explicitly and does not depend on the language used for the application interface.

Before export, a quality gate examines the composed report model. Critical findings block output. Warnings are logged without automatically preventing an otherwise permitted research export. A missing mandatory source therefore needs a different response from a limitation that readers must account for when assessing the result.

Layout also contributes to traceability. Tables need repeating headers, readable columns, and stable page breaks. The table of contents, cross-references, and bibliography should work in the final PDF. A report with values clipped at the page edge is not a good handover artefact, even if the calculation behind it was correct.

The Wiki article on reading a genome report provides a more detailed reading guide. The Genome help covers technical preparation and the local directories required before a run.

What the report does not claim

Genome is labelled Research Use Only. A report organises technical and scientific evidence, but it does not replace medical advice, diagnosis or treatment. It must not imply more certainty than the input data, method, or literature can support.

Negative results need particular care. “Not found” may mean that a variant was not detected in the region examined. It does not automatically exclude a risk. Some variant types are difficult to determine with a chosen method. Other associations have only been studied in particular populations or have small effect sizes. A responsible report states those limits instead of hiding them behind an unqualified colour.

Traceability is not a promise that every statement is final. It means readers can inspect the route to a statement: input, reference, quality status, analysis domain, and supporting evidence in the PDF. If knowledge or methods change, the report still shows which state was used at the time.

The current application is available from the download page for local workflows. A report earns its value from a chain that has kept its origin intact.