FASTA & Sequence Validation

Relevant source files

The following files were used as context for generating this wiki page:

• src/lib/fasta-validation.ts
• src/hooks/use-fasta-validation.ts
• src/components/services/fasta-textarea.tsx
• src/lib/forms/(genomics)/primer-design/primer-design-form-utils.ts
• src/lib/forms/(protein-tools)/msa-snp-analysis/msa-snp-analysis-form-utils.ts
• src/lib/forms/(viral-tools)/subspecies-classification/subspecies-classification-form-utils.ts

FASTA and sequence validation within the dxkb project provides a robust framework for ensuring that biological sequence data—whether DNA or protein—conforms to specific structural and character-based requirements before being processed by bioinformatics services. The system supports various input methods, including manual text entry and file-based selection, and applies tailored validation logic depending on the target service, such as BLAST, Primer Design, or MSA SNP Analysis.

The core validation engine is centralized in utility libraries that perform text cleaning, sequence type detection (DNA vs. Protein), and character verification. This ensures consistency across the user interface and prevents malformed data from reaching the backend API services.

Sources: src/lib/fasta-validation.ts, src/components/services/fasta-textarea.tsx

Core Validation Logic

The primary validation routine, validateFasta, processes raw text input to determine its validity based on a set of configurable options. It checks for sequence length, FASTA header presence, and valid character alphabets.

Validation Process Flow

The following diagram illustrates the standard steps taken to validate a FASTA input.

Sequence Type Detection

The isDNA function determines if a sequence is likely DNA by calculating the ratio of nucleotide characters (a, c, t, g, n) to the total sequence length (excluding gaps). A sequence is classified as DNA if this ratio is 0.75 or higher.

Sources: src/lib/fasta-validation.ts:54-75

Service-Specific Validations

Different bioinformatics tools require specific sequence formats. The project implements wrapper functions to enforce these requirements.

BLAST Validation

BLAST validation maps specific BLAST programs to their expected sequence types:

• DNA Requirements: blastn, blastx
• Protein Requirements: blastp, tblastn

Sources: src/lib/fasta-validation.ts:182-202

Primer Design Validation

Primer Design validation is more restrictive, often requiring a single DNA record and supporting custom markers (e.g., <>, [], {}) used to define excluded or target regions. It utilizes isInvalidSequence to ensure only a, g, c, t, n characters are present (excluding extended IUPAC codes).

Sources: src/lib/forms/(genomics)/primer-design/primer-design-form-utils.ts:145-210

MSA SNP Analysis

This module provides utilities to validate both general sequences and reference sequences. A reference sequence specifically requires numseq === 1.

Sources: src/lib/forms/(protein-tools)/msa-snp-analysis/msa-snp-analysis-form-utils.ts:82-108

Validation Status and Error Handling

The system returns a structured FastaValidationResult object containing detailed metadata about the validation attempt.

Field	Type	Description
valid	boolean	Indicates if the sequence passed all checks.
status	string	Machine-readable code (e.g., valid_dna, too_short, need_dna).
numseq	number	The total number of sequences detected in the input.
message	string	Human-readable error or status message.
trimFasta	string	The cleaned and formatted version of the input text.

Sources: src/lib/fasta-validation.ts:11-19

Components and Hooks

FastaTextarea Component

A specialized UI component, FastaTextarea, provides a debounced interface for sequence input. It automatically triggers validation as the user types and displays real-time feedback.

useFastaValidation Hook

The useFastaValidation hook encapsulates the state and logic for sequence validation, providing properties like isValidating, isValid, and errorMessage to consuming components.

Sources: src/hooks/use-fasta-validation.ts

Implementation Details

FASTA Cleaning Logic

The cleanFasta utility prepares raw strings for validation by:

1. Normalizing line endings to \n.
2. Removing empty lines.
3. Trimming whitespace from header lines (lines starting with >).
4. Removing all internal whitespace from sequence lines.

export function cleanFasta(fastaText: string): string {
  let newFasta = "";
  let records = fastaText.trim();
  // Normalize line endings
  records = records.replace(/[\r\n]/g, "\n");
  // ... split and process
  return newFasta;
}

Sources: src/lib/fasta-validation.ts:31-52

Character Alphabet Constraints

The general validator allows an extended amino acid alphabet: ABCDEFGHIJKLMNOPQRSTUVWXYZ and the gap character -. Service-specific validators, like Primer Design, restrict this further to only allow standard nucleotides.

Sources: src/lib/fasta-validation.ts:145-151, src/lib/forms/(genomics)/primer-design/primer-design-form-utils.ts:153-178

Conclusion

FASTA & Sequence Validation in dxkb is a multi-layered system that balances general biological rules with service-specific constraints. By providing centralized utilities and reactive UI components, the project ensures data integrity from the moment a user enters a sequence through to final API submission.