Output files

The output files Bases2Fastq™ produces

Output files for sequencing

The following table is a list of Bases2Fastq outputs files for sequencing:

File	Directory	Description
Bases2Fastq.log	info	Log file that records software events
IndexAssignment.csv	Root	Yield, number, and rate of polonies that are assigned for each sample and index combination
Metrics.csv	Root	Mismatch rates, percent assigned, and per sample yield for each lane
{ProjectName}_QC.html	Samples/{ProjectName}	Interactive HTML QC report on the performance and quality of the samples aggregated by project
{ProjectName}_IndexAssignment.csv	Samples/{ProjectName}	Yield, number, and rate of polonies that are assigned for each sample and index combination in a project
{ProjectName}_Metrics.csv	Samples/{ProjectName}	Mismatch rates, percent assigned, and per sample yield for each lane in a project
{ProjectName}_RunStats.json	Samples/{ProjectName}	Information on the performance of samples in a project
{RunName}_QC.html	Root	Interactive HTML QC report on run performance and quality for all samples and projects
RunManifest.csv	Root	Run manifest for the Bases2Fastq execution
RunManifest.json	Root	Machine-readable copy of the run manifest as a JSON file
RunManifestErrors.json	info	Record of errors in the run manifest
RunParameters.json	Root	Copy of the original run parameters file
RunStats.json	Root	Information on run performance
{SampleName}_{Read}.fastq.gz	Samples/{SampleName} or Samples/{ProjectName}/{SampleName}	The primary output of Bases2Fastq
{SampleName}_{Read}.fastq.gz.gzi	Same directory as the FASTQ file	BGZF block index for each FASTQ file. Generated only with --bgzf-compression.
{SampleName}_stats.json	Samples/{SampleName} or Samples/{ProjectName}/{SampleName}	Information on the performance of each sample in the run
started.json, completed.json	.attempts/{AnalysisID}	Record of when each execution that targets the output directory starts and completes
UnassignedSequences.csv	Root	The most frequent unassigned index sequences with approximate counts[^1]

[^1] ^{Counts indicate how many times an incorrect index sequence appears.}

Output files for multiomic runs

The following table is a list of Bases2Fastq output files for multiomic runs:

File	Directory	Description
Bases2Fastq.log	info	The log file that records software events
{RunName}_QC.html	Root	Interactive HTML QC report on run performance and quality for all batches and wells
{TargetSite}_{Well}_{Batch}_R1.fastq.gz	Samples/Well{Well}	The primary output of Bases2Fastq for targeted runs, triggered by --per-target-fastq
{Well}_{Batch}_R1.fastq.gz	Samples/Well{Well}	The primary output of Bases2Fastq for untargeted runs
Panel.json	Root	The panel file for the Bases2Fastq execution
RunManifest.csv	Root	The run manifest for the Bases2Fastq execution
RunManifest.json	Root	The machine-readable copy of the run manifest as a JSON file
RunParameters.json	Root	The copy of the original run parameters file
RunStats.json	Root	Information on run performance
started.json, completed.json	.attempts/{AnalysisID}	Record of when each execution that targets the output directory starts and completes
TargetCellAssignmentManifest.csv	Root	The target cell assignment manifest for the Bases2Fastq execution
TargetCellAssignmentManifest.json	Root	The machine-readable copy of the target cell assignment manifest as a JSON file

Attempt ledger

Each execution records itself in the .attempts folder of the output directory, in a subfolder named by the analysis ID. Bases2Fastq writes started.json when the execution starts and completed.json when it ends. The completed.json file includes a Success field and, for failed executions, an ErrorText field. Bases2Fastq does not delete the .attempts folder when it clears previous output.

If a local output directory already contains a record from a different execution, Bases2Fastq logs a warning. Concurrent or repeated writes to the same output directory can corrupt FASTQ files, so use a separate output directory for each execution.

FASTQ files

A FASTQ file records all genomic data and corresponding Q scores for a sample or cell. FASTQ files are GZIP-compressed text files that Bases2Fastq names {SampleName}_{Read}.fastq.gz for sequencing, and {Well}_{Batch}_R1.fastq.gz and {TargetSite}_{Well}_{Batch}_R1.fastq.gz for untargeted and targeted multiomic runs respectively. With the --bgzf-compression argument, Bases2Fastq writes BGZF-compressed FASTQ files and a .fastq.gz.gzi index file for each FASTQ file.

Each entry in a FASTQ file corresponds to one read and includes the following four lines:

• A sequence identifier that includes run and polony information
• Base calls that are assembled into a sequence comprised of A, C, G, T, and N
• A plus sign (+) that separates the sequence from the Q scores
• A Q score for each base in the sequence

Note:

If you use a sequencing run manifest with no samples or associated index sequences, then Bases2Fastq assigns all reads to DefaultSample. The software only produces the FASTQ files DefaultSample_R1.fastq.gz and DefaultSample_R2.fastq.gz.

Sequence identifiers for sequencing

The sequencing FASTQ sequence identifier includes the components in the following table and is formatted in one line:

@<instrument>_<model>:<run name>:<flow cell ID>:<lane>:<tile>:<x-pos>:<y-pos>:UMI <read>:N:0:<index sequence>

Component	Allowed Values	Description
@	@	Start to the sequence identifier line
<instrument>_<model>	Upper and lowercase letters, integers 0–9, dashes (-), and underscores (_)	Instrument name, suffixed with an underscore and the instrument model (for example, _AVITI) when RunParameters.json reports the model.
<run name>	Upper and lowercase letters, integers 0–9, hyphens (-), and underscores (_)	Run name that is defined during the run setup
<flow cell ID>	Upper and lowercase letters and integers 0–9	Flow Cell ID from the barcode scan. If the barcode scan fails during the run and no barcode is present, then FC- followed by the Run ID replaces the Flow Cell ID.
<lane>	An integer	Lane number. AVITI™ runs have lanes 1 and 2. Vitari™ runs can have up to 6 lanes.
<tile>	An integer	Tile number
<x_pos>	A zero-padded integer	X-coordinate of the polony. The value is 4 digits for AVITI runs and 5 digits for Vitari runs.
<y_pos>	A zero-padded integer	Y-coordinate of the polony. The value is 4 digits for AVITI runs and 5 digits for Vitari runs.
<UMI>	A, C, G, T, and N	UMI sequence with a plus sign that separates the Read 1 and Read 2 sequences, if applicable
<read>	1 or 2	Read number
<is filtered>	N	A legacy filtering value of N that exists only for backward compatibility and does not change
<control number>	0	A legacy control number of 0 that exists only for backward compatibility and does not change
<index sequence>	Varies	A value that is based on the indexing strategy that is indicated in the run manifest: No indexing: The sample number Single indexing: The observed index sequence Dual indexing: The observed Index 1 sequence, a plus sign, and the observed Index 2 sequence

Sequence identifiers for cell screening

The cell screening FASTQ sequence identifier includes the components in the following table and is formatted in one line:

@<instrument>_<model>:<run_name>:<flowcell_id>:<well_index>:<z_tile>:<xloc>:<yloc>:<cell_id>:<nuclear_status>:<batch_id>:<polony_index> 1:N:0:1

Component	Allowed Values	Description
@	@	The start to the sequence identifier line
<instrument>_<model>	Upper and lowercase letters, integers 0–9, dashes (-), and underscores (_)	Instrument name, suffixed with an underscore and the instrument model (for example, _AVITI) when RunParameters.json reports the model.
<run name>	Upper and lowercase letters, integers 0–9, hyphens (-), and underscores (_)	Run name
<flow cell ID>	Upper and lowercase letters, integers 0–9, and dashes (-)	Flow cell ID, FC-{RunID} if the flow cell ID is missing, or UNKNOWN_FLOWCELL if the flow cell ID and run ID are missing
<well_index>	2-digit, zero-padded integer	Well ID
<z_tile>	Numerical	The tile plus the z slice in the format of SRRCCZZ (surface, row, row, col, col, z, z)
<xloc>	4-digit, zero-padded integer	The x-coordinate of the polony
<yloc>	4-digit, zero-padded integer	The y-coordinate of the polony
<cell_id>	10-digit, zero-padded integer	The unique ID of the cell
<nuclear_status>	Boolean	The cellular location of a polony, whether the polony is in the nucleus or not. 0 is cellular and 1 is nuclear.
<batch_id>	String	The on-instrument cycling batch
<polony_index>	7-digit, zero-padded integer	Trailing polony index that resets for each z-tile. Prevents duplicate read identifiers when x or y coordinates are negative. Example: 0002538 in @…:0:B01:0002538.
<read>	1	Always 1 for cell screening
<is_filtered>	N	A legacy filtering value of N that exists only for backward compatibility and does not change
<control_number>	0	A legacy control number of 0 that exists only for backward compatibility and does not change
<indexsequence>	1	Always 1 for cell screening runs

Quality scores

A Q score is based on the Phred scale and indicates the confidence of a base call. A Phred quality score (Q) is logarithmically related to error rate (E): Q = -10log E.

In a FASTQ file, an ASCII code represents the Q score. Bases2Fastq encodes quality scores with a +33 offset (Phred33).

Q Score	ASCII Code	Character		Q Score	ASCII Code	Character		Q Score	ASCII Code	Character
0	33	!		19	52	4		38	71	G
1	34	"		20	53	5		39	72	H
2	35	#		21	54	6		40	73	I
3	36	$		22	55	7		41	74	J
4	37	%		23	56	8		42	75	K
5	38	&		24	57	9		43	76	L
6	39	'		25	58	:		44	77	M
7	40	(		26	59	;		45	78	N
8	41	)		27	60	<		46	79	O
9	42	*		28	61	=		47	80	P
10	43	+		29	62	>		48	81	Q
11	44	,		30	63	?		49	82	R
12	45	-		31	64	@		50	83	S
13	46	.		32	65	A		51	84	T
14	47	/		33	66	B		52	85	U
15	48	0		34	67	C		53	86	V
16	49	1		35	68	D		54	87	W
17	50	2		36	69	E		55	88	X
18	51	3		37	70	F		56	89	Y

HTML QC reports

Bases2Fastq generates a self-contained, interactive HTML QC report for sequencing and cell screening runs. The report requires no internet connection to view and records the Bases2Fastq command that produced it.

• For sequencing runs, the report includes overview, quality, indexing, lane, sample, adapter trimming, and run information sections. If the run includes more than 500 samples, then the report displays summary distributions and a searchable, sortable sample table instead of per-sample charts.
• For cell screening runs, the report includes overview, quality, lane, well, and run information sections.

Bases2Fastq names the QC report for a run {RunName}_QC.html and project-level QC reports for sequencing runs {ProjectName}_QC.html. Bases2Fastq skips the QC report for a run or project with zero reads. To skip QC report generation, use the --skip-qc-report optional argument.

HTML QC reports for individually addressable lanes

To generate HTML QC reports for each lane, create projects for each lane in your run manifest. For an example, see Using individually addressable lanes with projects.

Missing HTML QC report

If an HTML QC report does not generate on a system that is configured to run the static binary, then Bases2Fastq logs a warning and continues the execution. Complete the following troubleshooting steps:

1. Make sure that Python 3.8 or later is installed and available as python3.
2. Review the errors in info/QC.errors for the run report or info/{ProjectName}_QC.errors for a project report.

Metrics files

Bases2Fastq reports metrics in different files and formats to support different use cases:

• Metrics.csv offers a high-level overview of yield and assignment metrics, per lane and overall.
• IndexAssignment.csv summarizes index assignment rates per sample-index pair, per lane, and overall. The project-level index assignment CSV files provide metrics at the level of specific projects.
• The JSON metrics files provide aggregate metrics at the run, project, and sample levels with more details than the summary files. The sample-level files also provide metrics at the level of specific occurrences.

In Metrics.csv, IndexAssignment.csv, UnassignedSequences.csv, and the project-level CSV files, rows that aggregate metrics across all lanes have a Lane value of All. Rows for a single lane have the lane number.

Note:

For runs that use Cloudbreak™ UQ chemistry, output files with metrics only report PercentQ50. For other types of sequencing chemistry, the JSON files report PercentQ50 values of null, and the CSV files report PercentQ50 values of empty.

Run metrics for sequencing

The run metrics file RunStats.json reports the following sequencing run performance metrics in a JSON file format. These metrics are specific to the Bases2Fastq execution.

Metric	Value
AnalysisID	The unique identifier that Bases2Fastq generates for the analysis
AnalysisVersion	The current version of Bases2Fastq
AssignedYield	The run yield that is based on assigned reads in gigabases
FileVersion	The current version of the file format
FlowCellID	A flow cell identifier that is sourced from RunParameters.json. If blank, then FC- followed by the RunID value is used.
I1IsReverseComplement	The observed orientation of the Index 1 sequences relative to the orientation recorded in the run manifest. Reported per lane in Lanes.
I2IsReverseComplement	The observed orientation of the Index 2 sequences relative to the orientation recorded in the run manifest. Reported per lane in Lanes.
Lanes	A detailed list of per lane metrics
MeanReadLength	The average read length after adapter trimming. Reported per read in Reads.
NumPolonies	The total number of polonies that are calculated for the run
NumPoloniesBeforeTrimming	The total number of polonies that are calculated for the run before adapter trimming
PercentAssignedReads	The percentage of reads that are assigned to a sample
PercentBelowFilterThreshold	The percentage of all polonies that are below the quality filtering threshold. Reported per cycle in Reads.
PercentMismatch	The percentage of polonies that are assigned to a sample with a mismatch
PercentMismatchI1	The percentage of polonies that are assigned to Index 1 sequences with a mismatch. Reported per lane in Lanes.
PercentMismatchI2	The percentage of polonies that are assigned to Index 2 sequences with a mismatch. Reported per lane in Lanes.
PercentQ30	The percentage of ≥ Q30 Q scores for the run. This includes assigned and unassigned reads and excludes filtered reads and no calls.
PercentQ40	The percentage of ≥ Q40 Q scores for the run. This includes assigned and unassigned reads and excludes filtered reads and no calls.
PercentQ50	The percentage of ≥ Q50 Q scores for the run. This includes assigned and unassigned reads and excludes filtered reads and no calls.
PercentReadsTrimmed	The percentage of reads that Bases2Fastq trimmed. Reported per cycle in Reads.
PercentUnexpectedIndexPairs	The percentage of all polonies with Index 1 and Index 2 reads that matched different samples[^1]
PerReadMeanQualityScoreHistogram	The distribution of per-read average quality scores. Reported per read in Reads.
QualityScore10thPercentile	The 10th percentile of quality scores. Reported per cycle in Reads.
QualityScore25thPercentile	The 25th percentile of quality scores. Reported per cycle in Reads.
QualityScore50thPercentile	The 50th percentile of quality scores. Reported per cycle in Reads.
QualityScore75thPercentile	The 75th percentile of quality scores. Reported per cycle in Reads.
QualityScore90thPercentile	The 90th percentile of quality scores. Reported per cycle in Reads.
QualityScoreHistogram	A per-base call Q score distribution with integer resolution. Reported per read in Reads.
QualityScoreMean	The average Q score of base calls for the run and excludes filtered reads and no calls
Reads	A detailed list of per read metrics, including per cycle metrics in Cycles
RemovedAdapterLengthHistogram	A histogram that shows the number of bases trimmed from an adapter in a given position. Reported per read in Reads.
RunName	A text-based run identifier that is sourced from RunParameters.json
RunID	A universally unique identifier (UUID) that is assigned to the run and sourced from RunParameters.json
Samples	A list of libraries that the run sequenced
SampleStats	The per-sample metrics that are listed in the sample metrics files for the run
TotalYield	The total yield of all reads in gigabases
UnassignedSequences	A list of unassigned index sequences with a count for each unassigned sequence. Reported per lane in Lanes.

[^1] ^{For demultiplexing to be successful, both index reads must match the same sample.}

Project metrics for sequencing

When a run manifest groups samples by project, Bases2Fastq creates JSON project metrics files. Bases2Fastq names the files {ProjectName}_RunStats.json. The files report the following performance metrics for the samples in the project:

Metric	Value
AnalysisID	The unique identifier that Bases2Fastq generates for the analysis
AnalysisVersion	The current version of Bases2Fastq
AssignedYield	The project yield that is based on assigned reads in gigabases
FileVersion	The current version of the file format
FlowCellID	A flow cell identifier that is sourced from RunParameters.json. If blank, then FC- followed by the RunID value is used.
I1IsReverseComplement	The observed orientation of the Index 1 sequences relative to the orientation recorded in the run manifest. Reported per lane in Lanes.
I2IsReverseComplement	The observed orientation of the Index 2 sequences relative to the orientation recorded in the run manifest. Reported per lane in Lanes.
Lanes	A detailed list of per lane metrics
MeanReadLength	The average read length after adapter trimming. Reported per read in Reads.
NumPolonies	The total number of polonies that are calculated for the samples in the project
NumPoloniesBeforeTrimming	The total number of polonies that are calculated for the samples in the project before adapter trimming
PercentMismatch	The percentage of polonies that are assigned to samples with a mismatch in the project
PercentMismatchI1	The percentage of polonies that are assigned to Index 1 sequences with a mismatch. Reported per lane in Lanes.
PercentMismatchI2	The percentage of polonies that are assigned to Index 2 sequences with a mismatch. Reported per lane in Lanes.
PercentQ30	The percentage of ≥ Q30 Q scores for the project. This includes assigned and unassigned reads and excludes filtered reads and no calls.
PercentQ40	The percentage of ≥ Q40 Q scores for the project. This includes assigned and unassigned reads and excludes filtered reads and no calls.
PercentQ50	The percentage of ≥ Q50 Q scores for the project. This includes assigned and unassigned reads and excludes filtered reads and no calls.
PercentReadsTrimmed	The percentage of reads that Bases2Fastq trimmed. Reported per cycle in Reads.
Project	The alphanumeric project identifier
QualityScore10thPercentile	The 10th percentile of quality scores. Reported per cycle in Reads.
QualityScore25thPercentile	The 25th percentile of quality scores. Reported per cycle in Reads.
QualityScore50thPercentile	The 50th percentile of quality scores. Reported per cycle in Reads.
QualityScore75thPercentile	The 75th percentile of quality scores. Reported per cycle in Reads.
QualityScore90thPercentile	The 90th percentile of quality scores. Reported per cycle in Reads.
QualityScoreMean	The mean Q score of base calls for the samples in the project and excludes filtered reads and no calls
Reads	A detailed list of per read metrics, including per cycle metrics in Cycles
RemovedAdapterLengthHistogram	A histogram that shows the number of bases trimmed from an adapter in a given position. Reported per read in Reads.
RunName	A text-based run identifier that is sourced from RunParameters.json
RunID	A UUID that is assigned to the run and sourced from RunParameters.json
Samples	A list of libraries that are sequenced for the project
SampleStats	The per-sample metrics that are listed in the sample metrics files for the project

Sample metrics for sequencing

Sample metrics files report the following sample-specific performance metrics in the JSON file format. Bases2Fastq names the files {SampleName}_stats.json.

Metric	Value
AnalysisVersion	The current version of Bases2Fastq
BaseComposition	Counts for each A, C, G, T, and N base
ExternalID	An external ID that is specified in the run manifest, if applicable
FileVersion	The current version of the file format
MeanReadLength	The average read length after adapter trimming
NumPolonies	The total number of polonies that are assigned to the sample
NumPoloniesBeforeTrimming	The number of polonies that are assigned to a sample before adapter trimming
Occurrences	Additional information per occurrence of the sample
PercentMismatch	The percentage of polonies that are assigned to a sample with mismatch
PercentQ30	The percentage of ≥ Q30 Q scores for the sample. This includes assigned reads and excludes filtered reads and no calls.
PercentQ40	The percentage of ≥ Q40 Q scores for the sample. This includes assigned reads and excludes filtered reads and no calls.
PercentQ50	The percentage of ≥ Q50 Q scores for the sample. This includes assigned reads and excludes filtered reads and no calls.
PercentReadsTrimmed	The percentage of reads that Bases2Fastq trimmed
PerReadGCCountHistogram	A list of counts: the value at index i is the number of reads with i G/C calls
QualityScoreMean	The mean Q score of base calls for the sample and excludes filtered reads and no calls
RemovedAdapterLengthHistogram	A histogram that shows the number of bases trimmed from an adapter in a given position
RunName	A text-based run identifier that is sourced from RunParameters.json
RunID	A UUID that is assigned to the run and sourced from RunParameters.json
SampleID	A globally unique sample identifier
SampleName	The alphanumeric sample identifier
SampleNumber	The numeric sample identifier
Yield	The number of bases in the sample in gigabases

Run metrics for cell screening

The run metrics file RunStats.json reports the following cell screening run performance metrics in a JSON file format. These metrics are specific to the Bases2Fastq execution.

Metric	Value
AnalysisID	The unique identifier that Bases2Fastq generates for the analysis
AnalysisVersion	The current version of Bases2Fastq
BaseComposition	Counts for each A, C, G, T, and N base. Reported per position in Bases.
Bases	A detailed list of per position metrics for a well
BatchName	The name of a specific batch. Reported per batch in Batches.
Batches	A detailed list of per batch metrics, including per well metrics in Wells
FileVersion	The current version of the file format
FlowCellID	A flow cell identifier that is sourced from RunParameters.json. If blank, then FC- followed by the RunID value is used.
MeanReadLength	The average read length after adapter trimming. Reported per batch and per well.
NumPolonies	The total number of polonies that are calculated for the run
NumPoloniesBeforeTrimming	The total number of polonies that are calculated for the run before adapter trimming
PercentQ30	The percentage of ≥ Q30 Q scores for the run. This includes assigned and unassigned reads
PercentReadsTrimmed	The percentage of reads that Bases2Fastq trimmed. Reported per position in Bases.
PerReadMeanQualityScoreHistogram	The distribution of per-read average quality scores. Reported per batch and per well.
Position	The position index in FASTQ. Reported per position in Bases.
QualityScoreHistogram	The counts of base calls for each quality score bin. Reported per batch and per well.
QualityScoreMean	The average Q score of base calls and excludes filtered reads and no calls
ReadLengthHistogram	A histogram that shows the distribution of read lengths after trimming. Reported per batch and per well.
RunID	A universally unique identifier (UUID) that is assigned to the run and sourced from RunParameters.json
RunName	A text-based run identifier that is sourced from RunParameters.json
TotalYield	The total yield of all reads in gigabases
Wells	A detailed list of per well metrics for a batch, including per position metrics in Bases
WellLabel	The label for the wells that are specified in the well location column. Reported per well in Wells.
WellLocation	The location of the well on the flow cell. Reported per well in Wells.

Occurrences

Occurrences are a set of fields in a sample metrics file that allocate sample performance metrics by specific occurrences of a sample in the run. For example, if a sample appears in more than one lane, then Bases2Fastq lists an occurrence for each lane.

Each occurrence includes the identifiers Lane and Expected Sequence, and reports the following performance metrics:

Metric	Value
BaseComposition	Counts for each A, C, G, T, and N base
CustomMetadata	Custom metadata that is specified in the run manifest, if applicable
MeanReadLength	The average read length after adapter trimming
NumPolonies	The total number of polonies that are assigned to the sample
NumPoloniesBeforeTrimming	The number of polonies that are assigned to a sample before adapter trimming
PercentMismatch	The percentage of polonies that are assigned to a sample with mismatch
PercentQ30	The percentage of ≥ Q30 Q scores for the specific occurrence of a sample. This includes assigned reads and excludes filtered reads and no calls.
PercentQ40	The percentage of ≥ Q40 Q scores for the specific occurrence of a sample. This includes assigned reads and excludes filtered reads and no calls.
PercentQ50	The percentage of ≥ Q50 Q scores for the specific occurrence of a sample. This includes assigned reads and excludes filtered reads and no calls.
PercentReadsTrimmed	The percentage of reads that Bases2Fastq trimmed
PerReadGCCountHistogram	A list of counts: the value at index i is the number of reads with i G/C calls
QualityScoreMean	The mean Q score of base calls for the sample and excludes filtered reads and no calls
R1Adapters	The Read 1 adapter sequences that are associated with the lane that the occurrence belongs to
R2Adapters	The Read 2 adapter sequences that are associated with the lane that the occurrence belongs to
RemovedAdapterLengthHistogram	A histogram that shows the number of bases trimmed from an adapter in a given position
Yield	The number of bases in the sample in gigabases