Python function index

For a first reading, use functions in execution order. This generated index contains 493 functions and methods, including private and nested helpers, from the Python package. Sections follow workflow purpose; modules and names are alphabetical within them. Links open the exact definition. The Python API renders full docstrings. Legacy and experimental functions remain listed; their presence here does not make them part of the default runner.

Regenerate with python tools/render_function_index.py --write. CI checks the index against the source.

1. Prepare inputs and plan resources

fasta_lake.canonical

Function	Purpose
_find_local_canonical	Try to find a local canonical FASTA on the cluster.
_user_agent	Build the request identity, appending the optional configured contact.
download_canonical	Download the latest canonical SwissProt FASTA for an organism.
get_canonical	Get path to canonical FASTA, preferring local copy.

fasta_lake.capacity

Function	Purpose
_cgroup_limits	Read v1/v2 constraints at every ancestor up to the mounted hierarchy root.
_host_memory	Return total and available host memory in bytes from macOS or procfs.
_integer	Parse a positive capacity below 2**60, or return None for an unusable limit.
_read	Read a stripped system-limit file, returning an empty string on I/O failure.
_unescape_mount	Decode octal escapes in a Linux mount path.
detect_capacity	Observe capacity available to this process, not the cluster node's full RAM.
plan_laptop	Choose shared-process threads and reference pieces; never infer jobs per GB.

fasta_lake.complexity

Function	Purpose
_recommend_strategy	Auto-recommend inference strategy based on complexity metrics.
ComplexityReport.summary	Return summary dict for JSON stats output.
estimate_complexity	Estimate sample complexity by mapping peptides to a reference database.

fasta_lake.contaminants

Function	Purpose
_extract_accession	Extract UniProt-style accession from various header formats.
ContaminantDB.__post_init__	Populate the default contaminant accessions when none were supplied.
ContaminantDB.is_contaminant	True if this protein ID corresponds to a contaminant.
ContaminantDB.load	Load additional accessions from a text file (one per line).
ContaminantDB.load_from_fasta	Extract accessions from a FASTA file.
exclude_contaminants	Filter out PSM rows whose protein is a contaminant.
is_contaminant_id	Check if a protein_id is a contaminant. Cheap wrapper for FDR filters.
tag_contaminants	Rewrite protein IDs with CON_ prefix where they match contaminants.

fasta_lake.dianovo

Function	Purpose
parse_dianovo_prediction	Return a complete uppercase peptide and mean confidence, including zeros.

fasta_lake.downloads

Function	Purpose
_hashes	Stream SHA-256 and an optional expected MD5/SHA-256; reject mismatches.
_lock	Hold a directory lock for a download and release it on context exit.
_read_metadata	Fetch at most 2 MiB of resource metadata, raising for a larger response.
_safe_name	Reject empty names, directory traversal and embedded path separators.
catalogue	Return the installed, dated resource catalogue without making network calls.
download_file	Stream one planned file; publish only after size/checksum validation.
download_resource	Download a resolved resource into its named local folder, with per-file receipts.
free_bytes	Read free disk space from the closest existing destination parent.
inspect_remote	Read transfer metadata without downloading the resource body.
plan_download	Resolve files, transfer bytes, disk availability and expanded-size uncertainty.
resolve_resource	Resolve a catalogue choice, including live release identity for UniProt.
unpack_resource	Expand gzip/xz/tar archives into a fresh folder with a hard output-byte budget.
unpack_resource.copy_stream	Extract one safe archive member within the byte budget and record its hash.

fasta_lake.hashing

Function	Purpose
normalize_sequence	Normalize an amino-acid sequence per the frozen hashing contract.
sequence_hash	Return the v5.3 SHA256 hex digest of a normalized amino-acid sequence.

fasta_lake.headers.init

Function	Purpose
_build_gene_map	Build accession → gene and description → gene maps from canonical FASTA.
_parse_disease_variant	Parse disease variant format: sp|P02649_v21K|APOE_VAR description.
_parse_ens_variant	Parse personal variant format: ens|ENST_Mut|GENE description
_parse_ensembl_pep	Parse Ensembl pep format: ENSP... pep chromosome:... gene:ENSG... gene_symbol:XXX
_parse_gencode	Parse GENCODE format: ENSP|ENST|ENSG|OTTHUMG|OTTHUMT|transcript-NNN|GENE|length
_parse_gnomad	Parse gnomAD variant format: var-POP|ACC|GENE_Mut|pos [sp|...|... desc GN=GENE]
_parse_lake_hybrid	Parse lake_builder output: PROJECT [SWISSPROT] sp|ACC|NAME desc GN=GENE md5=...
_parse_mgyg	Parse UHGP/MGYG format: MGYG000000000_00000 description
_parse_ncbi_microbe	Parse NCBI microbe format: SPECIES|WP_ACC|LOCUS [gene=X] description OS=...
_parse_prodigal	Parse Prodigal format: 1_1 # start # end # strand # ID=1_1;partial=...
_parse_sample_ref	Parse SAMPLE|REF| prefix format from Stage 2 output.
_parse_simple_microbe	Parse simple microbe formats: GMGC, SMORF, Assembly.
_parse_uniprot	Parse UniProt sp| or tr| format.
_resolve_gene	Try to resolve a missing gene name using canonical mapping.
audit_fasta	Audit a FASTA file's headers without modifying it.
generate_decoys	Generate reversed decoy sequences and append to FASTA.
heal_fasta	Heal a FASTA file for a specific search engine.
parse_header	Parse a FASTA header line (without leading '>') into a ParsedHeader.
ParsedHeader.format_for_diann	Format header for DIA-NN compatibility.
ParsedHeader.format_for_msfragger	Format header for MSFragger/Philosopher compatibility.
ParsedHeader.format_for_sage	Format header for SAGE compatibility.
prepare_fasta_for_engine	Prepare a FASTA file for a specific search engine.
print_audit	Pretty-print audit results.

fasta_lake.headers.main

Function	Purpose
main	Parse and dispatch the FASTA header healing, audit and preparation commands.

fasta_lake.headers.fasta_io

Function	Purpose
load_fasta_full	Load FASTA file preserving full headers.
load_fasta_full._flush	Store the pending FASTA record, rejecting empty sequences and duplicate IDs.
load_fasta_proteins	Load FASTA file returning protein_id → sequence (backward compatible).
write_fasta	Write FASTA file with full headers.
write_fasta_simple	Write a subset of proteins to FASTA with full headers.

fasta_lake.headers.validation

Function	Purpose
detect_experiment	Auto-detect experiment type from de novo CSVs and mzML filenames.
print_validation	Pretty-print validation results.
validate_denovo_csv	Validate a de novo prediction CSV before processing.
validate_evidence_lake	Validate evidence lake output from fasta_extractor.
validate_inference_output	Validate Stage 3 inference output.
validate_mzml	Validate an mzML file before processing.
validate_persample_fasta	Validate per-sample FASTA from Stage 2.
validate_pipeline	Run all validation checks on available pipeline outputs.
validate_source_fasta	Validate a source FASTA file before lake building.

fasta_lake.helpers

Function	Purpose
_accession_from_header	Read the first header token, reporting the source line for an empty header.
_store_record	Refuse duplicate accessions and empty sequences instead of losing records.
clean_sequence	Clean a protein sequence by uppercasing and removing stop codons.
collect_peptides_with_scores	Collect peptides with their best AlphaNovo scores from a CSV file.
count_fasta_headers	Number of '>' records in a FASTA file, read with the file closed afterwards.
get_db_type	Classify a protein by its database source based on ID prefix.
get_species_id	Extract a species/genome identifier from a protein ID, or None.
load_fasta_proteins	Load proteins from a FASTA file into a dict.
load_fasta_proteins._flush	Pass the pending FASTA record to the shared record validator.
map_peptides_to_proteins	Map peptides to proteins using Aho-Corasick multi-pattern matching.
normalize_il	Normalize isoleucine (I) to leucine (L) for mass spec equivalence.
require_columns	Raise ValueError when a table lacks the columns a reader depends on.

fasta_lake.lake_builder

Function	Purpose
_parse_gencode_header	GENCODE: >ENSP00000269305.4|ENST...|ENSG...|gene_name|desc
_parse_generic_header	Preserve the first header token as accession and the remaining description.
_parse_uhgp_header	UHGP: >MGYP000123 description
_parse_uniprot_header	Parse UniProt metadata into a source record, or return None for other headers.
build_lake	Build a merged lake FASTA + provenance sidecar from multiple sources.
iter_fasta	Yield (SourceRecord, sequence) pairs from a FASTA, tagging every record
parse_header	Parse a FASTA header line (without leading >).

fasta_lake.lake_merge

Function	Purpose
_merge_description	Prefer the longest informative description; fall back to longest.
_merge_gene	First non-empty gene in priority order.
_merge_organism	If all sources agree → that organism. Else → 'ambiguous', list conflicts.
_merge_pe	UniProt PE: LOWER is stronger evidence. Return min across sources.
_merge_sv	Return the highest recorded sequence version, or None when all are absent.
_merge_tax_ids	Collect distinct recorded taxonomy IDs in numeric order.
_primary_source	Return the SourceRecord that won primary status, or None if not found.
_priority_index	Return a source's priority position, sorting unknown tags after known ones.
_record_to_jsonable	Convert MergedRecord to a JSON-serialisable dict (flattens dataclasses).
format_fasta_header	Format the merged FASTA header line (without leading >).
merge_records	Merge N source records that share an identical sequence into one.
priority_win	Legacy behaviour: pick one winner by priority, discard other sources.
read_provenance_sidecar	Read a provenance sidecar JSONL (or JSONL.gz) back into MergedRecords.
write_provenance_sidecar	Write merged records as JSONL (or JSONL.gz if compress=True).

2. Select acquisition databases

fasta_lake.blosum

Function	Purpose
_parse_matrix	Parse a whitespace-delimited substitution matrix into residue-pair scores.
generate_all_variants	Generate all single-substitution variants for a sequence.
generate_variants	Generate single-AA variants at a position.
score	Substitution score for aa1 -> aa2.
substitutions	Possible substitutions for an amino acid, sorted by score descending.

fasta_lake.chunked

Function	Purpose
_pieces	Yield complete-record pieces without buffering a whole FASTA record.
_predictions	Mirror Rust's recursive, case-sensitive CSV roster, including symlink files.
_sha	Stream a file into a lowercase SHA-256 hex digest.
_stamp	Record a file's byte count and SHA-256 without loading it into memory.
extract_chunked	Extract and merge without altering the prepared input lake's identities.

fasta_lake.ics

Function	Purpose
add_ics	Add ICS column to search results. Auto-detects engine from columns.
add_ics_alphapept	Add ICS column to AlphaPept results.
add_ics_sage	Add ICS column to SAGE results.
clean_sequence	Strip modifications, keep uppercase AA only.
ics	Core ICS formula. Returns 0-1.
summarize	ICS summary statistics.

fasta_lake.inference.runner

Function	Purpose
_rescue_failed_peptides	Run mass k-mer anchoring on peptides that failed exact matching.
run_inference	Run protein inference on a single sample.

fasta_lake.inference.strategies

Function	Purpose
infer_bayesian	Bayesian protein probability: iterative evidence redistribution.
infer_info_score	Information-content parsimony: keep proteins above an info score threshold.
infer_razor	Razor parsimony: assign shared peptides to protein with most unique peptides.
infer_razor._protein_sort_key	Rank the Python razor candidates by support, with lexical accession ties.
infer_species_budget	Species-budget parsimony: cross-species aware shared peptide resolution.
infer_species_budget._protein_sort_key	Rank by optional unique-score support, then evidence counts and accession.
infer_uniform	Uniform parsimony: keep ALL proteins with any peptide evidence.
infer_uniform_2pep	Uniform 2-peptide: require at least min_peptides per protein.
score_lake_bayesian	Score every protein in the evidence lake using Bayesian EM across ALL samples.

fasta_lake.refine

Function	Purpose
generate_variant_fasta	Write a proposal FASTA: one best-scoring substitution per candidate protein.
identify_refinement_candidates	Find low-ICS PSMs that are candidates for variant refinement.
run_refinement	Not implemented: a validated refinement pass does not exist yet.

3. Add molecular evidence

fasta_lake.multi_omics.main

Function	Purpose
_add_gate_args	Add options for the historical clustered FL_MO evidence-gate command.
main	Dispatch the historical FL_MO gate or frozen-median reproduction command.

fasta_lake.multi_omics.cli

Function	Purpose
add	Keep a final de novo FASTA and append DNA/RNA/metabolite-supported proteins.
checked	Translate expected input and execution failures into readable Click errors.
compare_searches	Compare exact proteins, accepted peptides and LFQ in two matched Sage searches.
increments	List gained/lost peptide and protein support against one complete reference.
molecular	Prepare TPM inputs, select exact proteins and compare matched searches.
prepare_source	Check and copy specimen inputs into a new portable source directory.
select	Build a standalone molecular FASTA with an optional common background.
selection_options	Build a Click decorator for independent DNA/RNA selection thresholds.
selection_options.decorate	Attach source, specimen, output and molecular-selection options in order.
validate_source	Check source hashes, gene agreement, annotation links and declared scope.

fasta_lake.multi_omics.complementarity

Function	Purpose
compare	Compare two searches of the same acquisition with identical non-file settings.
correlation	Return Pearson correlation, or None for fewer than two or constant values.
finite	Convert a value to float and reject NaN or infinity with a field label.
load_search	Read accepted target evidence and positive LFQ features for one acquisition.
peptide	Validate a Sage peptide and remove modification syntax before I/L collapse.
rank	Return one-based ranks in input order, averaging the ranks of tied values.
search_inputs	Resolve a single-acquisition search and separate settings from file paths.

fasta_lake.multi_omics.evidence_gate

Function	Purpose
build_evidence_lookup	Build the per-sample evidence attribution table (the FL_MO core).
EvidenceRow.has_tpm	Report whether either historical DNA or RNA support flag is set.
EvidenceRow.in_gate	Whether this representative is admitted under the given gate.
EvidenceRow.to_tsv	Serialize this legacy gate row, formatting TPM to four decimal places.
gate_members	Return the set of cluster_rep_ids admitted under gate.
passes_tpm	Return (passes_metaG_top1, passes_metaT_1) for a single assembly protein.
top1_threshold	Per-sample metaG cutoff: smallest value v* such that values >= v* are the

fasta_lake.multi_omics.exact

Function	Purpose
build_union	Keep every baseline sequence and append independently selected molecular proteins.
load_source	Load one explicitly specimen-qualified quantification reference.
numeric	Parse a nonnegative finite TPM while preserving explicit missing tokens.
read_fasta	Return accession -> (full header, normalized sequence, SHA-256).
read_fasta.save	Store a normalized record with its exact-sequence hash, enforcing ID limits.
read_tpm	Read plain or gzipped gene TPM rows without converting missing values to zero.
sha256	Hash file bytes in 8 MiB blocks and return the SHA-256 hex digest.
top_cutoff	Top percentage among positive GENES; zero disables, ties all included.
write_table	Write dictionary rows as a TSV, using deterministic gzip for a .gz path.

fasta_lake.multi_omics.increments

Function	Purpose
evidence_tables	Return exhaustive support rows and bidirectional counts.
increment_report	Validate matched searches and export complete reference-wide evidence.
reference_map	Map I/L-canonical peptides to distinct exact protein sequences.

fasta_lake.multi_omics.reproduce

Function	Purpose
per_sample_median	Return (median, n_samples) of an integer depth column in a per-sample TSV.
reproduce	Recompute and check the published FL_MO razor median.

fasta_lake.multi_omics.runner

Function	Purpose
_denovo_rep_ids	First-token header ids from the de-novo extracted FASTA.
_f	Parse a legacy TPM value, treating blank or malformed text as zero.
_pull_rep_seqs	Stream the rep FASTA, returning {rep_id: raw_sequence_bytes} for needed.
index_fasta	Return {first_whitespace_token_of_header: sequence_str} for a FASTA.
load_hash_to_rep	Load the FL_MO hash_to_rep table: {sha256_hex: cluster_rep_id}.
load_tpm_tsv	Yield (assembly_protein_id, metaG_tpm, metaT_tpm) from a TPM TSV.
run_fl_mo_sample	Run the FL_MO gate for one sample and write the augmented FASTA + lookup.

fasta_lake.multi_omics.selection

Function	Purpose
_targets	Read target-only proteins and index exact sequences by SHA-256.
build_selection	Select gene-supported sequences and write a traceable target FASTA union.
validate_rules	Validate independent DNA/RNA selection modes without loading any inputs.

fasta_lake.multi_omics.sources

Function	Purpose
_inputs	Resolve source-manifest paths and verify required inputs and pinned hashes.
_load_v2	Validate a specimen-qualified v2 source, its sequence coverage and annotations.
load_reference	Load a v1/v2 source.json and verify its pinned files and reference contract.
MolecularSource.available	Return sorted genes with both a TPM row and a protein sequence.
MolecularSource.coverage	Summarize available sequences, unavailable genes and missing molecular values.
prepare_source	Package checked specimen-matched molecular inputs for portable reuse.
table_rows	Yield string-valued rows from plain/gzipped TSV with a complete unique header.
write_coverage	Write missing-gene and measurement coverage to a caller-owned output directory.
write_reference	Write every available exact sequence, including genes with zero/missing TPM.

4. Search, group and quantify

fasta_lake.aggregate

Function	Purpose
build_quant_matrix	Build a quantification matrix across samples.
compute_cross_sample_stats	Compute cross-sample statistics.
load_diann_sample	Load a single-sample DIA-NN report.
print_cohort_summary	Print a summary table of all samples.
run_rust_aggregation	Run the Rust aggregation_engine binary.

fasta_lake.quantification

Function	Purpose
_baseline	Validate the sum matrix without requiring numerical packages for sum mode.
_directlfq	Run directLFQ on ions assigned to the fixed study dictionary.
_peptide_support	Write observed peptide support before/after estimation, one acquisition at a time.
_read_frame	Read a TSV with pandas while preserving identifier-like NA strings.
quantify_study	Quantify an existing study dictionary without assigning peptides again.
require_directlfq	Fail before running a workflow if the optional backend is unavailable.
stamp	Return basename, byte size and a streamed SHA256 for a pathlib.Path input.

fasta_lake.search

Function	Purpose
_dda_config	The explicitly versioned DDA settings used in the release acceptance runs.
sage_config	Build the complete configuration for one Sage v0.14.7 acquisition.

fasta_lake.study

Function	Purpose
_members	Collect distinct nonempty accessions, excluding the rev_ decoy prefix.
_passing	Accept only a finite q value between zero and the inclusive threshold.
_peptide_evidence	Retain accepted identifications, including peptides without positive LFQ features.
_quantify	Assign positive finite LFQ features to the fixed peptide-to-group dictionary.
_rank_one	Require a positive integer Sage rank and retain only the first hit.
_read_fasta	Verify accession identity before merging acquisition evidence.
_read_fasta.retain	Merge a nonempty FASTA record after checking local IDs and sequence identity.
_rows	Hash the actual bytes read, then parse strict, tab-delimited records.
_rows.lines	Decode TSV lines while hashing exactly the bytes consumed by the parser.
_sage_filename	Sage emits the basename including mzML extension; accept recorded full paths.
_write_table	Create a TSV exclusively, preserving the caller's column and row order.
canonical_peptide	Remove Sage modifications and use the declared I/L equivalence.
greedy_set_cover	Choose study representatives by maximum uncovered peptide gain.
group_searches	Build study groups and sum quantities from completed acquisition searches.
member_set_key	Preserve the full distinct accession membership, without source-tag stripping.
study_dictionary	Assign accepted peptides to a fixed set of study representatives.

5. Inspect and interpret results

fasta_lake.annotation

Function	Purpose
annotate_fasta	Run eggNOG-mapper 2.1.12 on exact unique selected sequences.
annotate_study	Annotate the exact representatives exported by a completed study grouping.
prepare_annotation_targets	Deduplicate a selected FASTA by exact sequence; retain every input alias.
read_annotation_settings	Validate optional annotation settings; resolve local paths beside the JSON file.
read_eggnog_annotations	Read v2 eggNOG output and retain no-hit and hit-without-function queries.

fasta_lake.community_plots

Function	Purpose
plot_community_context	Plot both count and summed-signal fractions; keep empty acquisitions visible.

fasta_lake.downstream

Function	Purpose
_names	Read unique nonblank IDs and require them to belong to the expected roster.
_plot	Save descriptive QC panels and the eligible PCA result using local plot styles.
_plot.draw_pca	Draw available finite PCA scores, or show why no PCA coordinates were saved.
analyze_study	Summarize study coverage and plot eligible PCA without imputing quantities.
require_analysis	Load the pinned QC backend and return AlphaPeptTools, AnnData, NumPy and pandas.

fasta_lake.embeddings

Function	Purpose
embed_unknown	Embed every unknown from a completed, unchanged FastaLake annotation run.
residue_embedding_sum	Sum residue embeddings in float64, excluding the ESM-C BOS/EOS tokens.
resolve_checkpoint	Validate an explicit local checkpoint against its published upstream SHA256.
sequence_windows	Yield nonoverlapping full-coverage windows; never silently truncate a protein.

fasta_lake.exploration

Function	Purpose
_plot	Render coverage beside annotated-feature diversity; label experimental scope.
explore_study	Export functional signal, coverage, diversity, Bray–Curtis and CLR PCA.
read_group_terms	Read a long table with study_group and term columns; deduplicate exact pairs.

fasta_lake.metaproteomics

Function	Purpose
_matrix	Validate a nonempty feature-by-acquisition frame and return numeric values.
_within_group_ss	Sum within-group squared distances, dividing each pair by its group size.
aggregate_terms	Split observed group signal equally across distinct declared functional terms.
bray_curtis	Return a labelled Bray–Curtis distance matrix and explicitly excluded samples.
clr_complete	Return sample × feature natural-log CLR on the complete positive core.
diversity_summary	Return observed richness, Shannon entropy and effective Shannon diversity.
permanova	One-way experimental PERMANOVA with optional within-block label permutations.
permanova.align	Align complete acquisition labels to the distance matrix and encode groups.
permanova.statistic	Compute the PERMANOVA pseudo-F statistic for the supplied group labels.
permanova.within	Compute within-group dispersion for one observed or permuted label vector.
permanova.within	Compute within-group dispersion for one observed or permuted label vector.
relative_signal	Close observed signal to one per nonempty acquisition; preserve empty columns.

fasta_lake.network_annotations

Function	Purpose
annotate_evidence_network	Attach annotations to exact sequences from a recorded study FASTA.
function_terms	Split one annotation namespace without creating terms for missing values.
load_eggnog_annotations	Read a completed FastaLake annotation folder or native eggNOG v2 output.

fasta_lake.networks

Function	Purpose
_identity	Validate a nonblank identifier without padding or control characters.
_integer	Parse an integer at least minimum, rejecting noncanonical numeric text.
_rows	Yield exact-schema TSV rows, enforcing the caller's row limit.
_sha	Return a streamed SHA-256 digest of the evidence file.
add_function_annotations	Extend a bounded view with typed orthology edges without changing assignments.
export_evidence_network	Write complete typed tables and a checked portable graph JSON in a new folder.
load_evidence_network	Read an unchanged, completed network export; reject partial or modified bundles.
load_network_annotations	Read an unchanged functional layer belonging to the requested evidence graph.
read_evidence_network	Read and reconcile a schema-1 study's complete reported-membership graph.
read_evidence_network.node_id	Derive a kind-prefixed node ID from the graph identity and node label.
render_ckg_network	Render a portable export with the user's separate compatible CKG environment.
select_network_view	Select a deterministic bounded view, prioritizing shared peptide memberships.

fasta_lake.proteomics.cascade

Function	Purpose
_canonical_peptide_set	Pool tryptic peptides from the canonical FASTA under the supplied digest limits.
build_smart_tier	canonical backbone + smart isoforms + Ig + variants, gene-healed.

fasta_lake.proteomics.grouping

Function	Purpose
_norm_name	Lowercase a protein name and remove fragment and isoform qualifiers.
_set_gene	Replace the first GN= token, or append it when absent.
assign_gene	Return (gene, method).
build_gene_index	Build the discriminative peptide->gene index from canonical SwissProt.
heal_fasta_genes	Rewrite GN= in input_fasta with peptide-voted real gene symbols. Returns stats.
is_accession_gene	True if GN= is actually a UniProt accession (i.e. a fake gene).
is_ig	Test whether the header matches the configured immunoglobulin pattern.
iter_fasta	Yield (header_without_gt, sequence).
parse_gene	Return the first GN= gene token, or None when the header has none.
parse_protein_name	Protein description between the id token and the first KEY= tag.
tryptic_peptides	Cut after K/R (no proline rule — matches the run's --cut 'K*,R*'). I/L folded.

fasta_lake.qc_plots

Function	Purpose
intensity_distribution_summary	Summarise measured positive reporting-group intensities per acquisition.
plot_intensity_distributions	Save paginated violins, missingness bars and their exact summary table.

fasta_lake.quality

Function	Purpose
compute_sequence_entropy	Compute normalized Shannon entropy of a protein sequence.
filter_sequences_by_quality	Apply sequence quality filters to a protein dictionary.
has_poly_run	Check if a sequence contains a homopolymeric run.
is_fragment	Check if a protein is likely a fragment.
noncanonical_fraction	Fraction of residues outside the 22 genetically encoded amino acids.
normalise_residues	Clean a protein sequence: strip trailing stop symbols, replace non-canonical
QualityReport.summary	Return summary dict for JSON stats output.

fasta_lake.taxonomy

Function	Purpose
_balance	Classify an assigned lineage as host, bacteria, archaea or other; retain unresolved.
_write_report	Embed upstream Unipept visualisations and data for an offline HTML report.
build_taxonomy_tree	Make Unipept's count/selfCount tree with each peptide's weight counted once.
canonical_peptide	Use the study's I/L-equivalent peptide identity, without removing mass gaps.
prepare_unipept_queries	Export the checked study peptide roster for the upstream Unipept CLI.
read_unipept_output	Read native pept2lca --all JSON/CSV; keep absent and truncated lookups visible.
taxonomy_report	Create local taxonomy/holobiont plots from Unipept output, without web requests.

fasta_lake.taxonomy_reference

Function	Purpose
prepare_unipept_reference	Write sa-builder's four-field TSV from a selected protein FASTA.

6. Run the workflow and configure tools

fasta_lake.annotation_cli

Function	Purpose
annotation	Annotate selected proteins and inspect explicit annotation gaps.
eggnog_cmd	Run eggNOG-mapper 2.1.12 with versioned inputs and complete coverage records.
embed_cmd	Embed the recorded unknown roster; preserve every residue through windowing.
study_cmd	Annotate a study's verified reporting representatives, with optional ESM-C.

fasta_lake.cli

Function	Purpose
_Legacy.invoke	Print the legacy notice to stderr, then run the command unchanged.
_LegacyGroup.invoke	Print the legacy notice to stderr, then run the command unchanged.
_maybe_inject_entrapment	Apply a config's entrapment section to a database, returning what to search.
_setup_logging	Configure logging for CLI usage.
analyze_study_cmd	Export AnnData and run AlphaPeptTools QC, log2 PCA and optional replicate CV.
cli	FASTA Lake: Sample-specific protein database construction for metaproteomics.
contam_list	List the bundled contaminant accessions.
contam_tag	Scan a FASTA, prefix CON_ on headers matching the contaminant list.
contaminants_grp	Inspect or apply the contaminant database (v5.1).
convert	Convert raw mass spec data to de novo predictions.
diagnose_cmd	Produce FDR calibration curve + outlier sample list.
entrapment_classes_cmd	List entrapment classes with their difficulty and interpretation.
entrapment_fdp	Compute the FDP from search results, with n, median, IQR and bootstrap CI.
entrapment_generate	Produce an entrapment FASTA, deterministically.
entrapment_grp	Generate, inject and measure entrapment sequences.
entrapment_inject	Concatenate entrapment into a database and write a manifest.
entrapment_prefixes	Report the entrapment prefixes actually present in a FASTA.
entrapment_prepare	Generate + inject entrapment as configured by a fastalake.json.
evidence_lake	Stage 1: Create evidence lake from peptide predictions.
export	Prepare a FASTA for a specific search engine.
extract_chunked_cmd	Build evidence in bounded reference pieces and merge before inference.
extract_sample	Stage 2: Extract per-sample protein database.
fl_mo_gate	Run the FL_MO gate for one sample at Stage 3.
fl_mo_grp	Legacy clustered FL_MO reproduction (archived Methods §M5.5).
fl_mo_reproduce	Reproduce the published FL_MO razor per-sample median (13,776).
group_study_cmd	Group and quantify completed Sage searches (fasta-lake group-study --help).
infer	Experimental Python inference, distinct from the validated Rust workflow.
init	Generate an example fastalake.json configuration.
lake_build	Stage 0: Build reference protein lake from databases.
lake_inspect_cmd	Query a lake provenance sidecar produced by lake-merge.
lake_merge_cmd	Merge multiple source FASTAs into one lake with field-level annotation merge (v5.2).
plan_resources_cmd	Show laptop planning choices without starting a workflow.
preset_grp	Inspect or export the legacy parameter presets of the infer route.
preset_list	List registered parameter presets and their search thresholds.
preset_sage	Emit a SAGE config with a preset applied.
preset_show	Show all parameters for a preset.
quantify_study_cmd	Quantify completed study groups and retain peptide/ion support diagnostics.
run_cmd	Run the whole study from an acquisition manifest (fasta-lake run --help).
tune_cmd	Recommend SAGE parameters by post-hoc sweep over existing entrapment results.
validate	Validate a FASTA Lake JSON configuration file.

fasta_lake.config

Function	Purpose
ClusteringConfig.__post_init__	Require identity and coverage fractions in the interval (0, 1].
ClusteringConfig.min_seq_id	The value to pass as MMseqs2 --min-seq-id.
ClusteringConfig.mmseqs_args	The MMseqs2 easy-cluster argument list driven by this config.
ClusteringConfig.skip_clustering	True when clustering is a no-op for this config.
create_example_config	Generate an example JSON configuration string.
DatabaseConfig.__post_init__	Convert source dictionaries into validated DatabaseSource objects.
DatabaseSource.__post_init__	Normalize the source path and reject unsupported source categories.
EntrapmentConfig.__post_init__	Normalize the injection stage and validate seed, count and FDR settings.
FastaLakeConfig.__post_init__	Normalize and validate acquisition and search-engine names.
FastaLakeConfig.get_sources_by_type	Return database sources filtered by type.
FastaLakeConfig.has_contaminants	Check if contaminant databases are configured.
FastaLakeConfig.has_entrapment	Check if entrapment is configured (via config or source tags).
FastaLakeConfig.has_variants	Check if variant databases are configured.
FastaLakeConfig.validate	Validate that required fields are set and paths are sensible.
InferenceConfig.__post_init__	Reject an inference strategy absent from the supported strategy registry.
load_config	Load a FASTA Lake configuration from a JSON file.
OutputConfig.__post_init__	Normalize the configured output path to a string.

fasta_lake.download_cli

Function	Purpose
download_cmd	Show the plan, then explicitly download one chosen resource; do not unpack.
list_cmd	Show installed choices and dated sizes; this command is offline.
plan_cmd	Show release, download bytes and disk needs without downloading data.
resources	Choose, size and download public reference databases and model weights.
show_plan	Print the selected resource, destinations, size estimates and checksums.
size_label	Format bytes as GiB and exact bytes; preserve an unknown estimate as text.
unpack_cmd	Unpack archives into a new directory within an explicit disk budget.

fasta_lake.exploration_cli

Function	Purpose
explore_cmd	EXPERIMENTAL: inspect annotated signal, coverage, diversity and CLR PCA.

fasta_lake.gzip_io

Function	Purpose
open_gzip_text	Open path for writing gzip-compressed text with a zero MTIME header.

fasta_lake.network_cli

Function	Purpose
eggnog_cmd	Attach eggNOG annotations by exact protein sequence; retain unknowns.
export_cmd	Export complete accepted memberships from a group-study result.
network	Export peptide memberships and render experimental CKG network views.
render_cmd	Create an experimental CKG report from a completed export.

fasta_lake.presets

Function	Purpose
apply_preset	Apply preset fields to an existing RunConfig-like object.
describe_preset	Human-readable description of what a preset does.
get_preset	Return the named preset or raise ValueError listing the available names.
Preset.as_dict	Return a dataclass dictionary of this preset's settings.
preset_sage_config	Apply preset to a SAGE JSON config dict. Returns modified copy.

fasta_lake.provenance

Function	Purpose
summarise_provenance	Aggregate a provenance JSONL into summary counts.
write_provenance	Write per-protein provenance sidecar.

fasta_lake.resources

Function	Purpose
local_interpreter	Keep a Python environment's launch path, including its executable symlink.
run_recorded	Record POSIX child usage when available.

fasta_lake.run_config

Function	Purpose
RunConfig.capture_environment	Auto-populate environment fields (git commit, binary paths, etc.).
RunConfig.load	Load config from JSON/YAML.
RunConfig.max_length	Read the legacy length alias, or set both de novo and search maxima.
RunConfig.max_length	Read the legacy length alias, or set both de novo and search maxima.
RunConfig.min_length	Read the legacy length alias, or set both de novo and search minima.
RunConfig.min_length	Read the legacy length alias, or set both de novo and search minima.
RunConfig.save	Save config to YAML.
RunConfig.summary	Human-readable summary.
RunConfig.update_cluster	Update config with clustering results.
RunConfig.update_evidence	Update config with evidence lake results.
RunConfig.update_sample	Update config with per-sample extraction results.
RunConfig.update_search	Update config with search results for one sample.

fasta_lake.rust.binaries

Function	Purpose
find_binary	Locate a compiled Rust binary.
run_fasta_extractor	Run the Rust fasta_extractor binary.
run_lake_builder	Run the Rust lake_builder binary.

fasta_lake.study_cli

Function	Purpose
main	Parse grouping options, validate optional backends, then group and report the study.

fasta_lake.taxonomy_cli

Function	Purpose
prepare	Write canonical peptides for Unipept pept2lca --all --equate.
prepare_reference	Experimental: export a selected FASTA for Unipept's native index builder.
report	Render upstream sunburst/treemap/tree with explicit counts, signal and citations.
taxonomy	Export Unipept queries and plot its saved taxonomic assignments locally.

fasta_lake.workflow

Function	Purpose
build_parser	Define every fasta-lake run option with its help text and default.
entry	Run :func:main and turn expected failures into a one-line error and exit 1.
load_manifest	Validate acquisitions and resolve inputs relative to the manifest.
main	Validate and execute the acquisition-manifest workflow.
main.execute	Run one command with resource measurements and append its result to commands.json.
main.extract	Run whole-reference or chunked exact lookup with the same declared evidence settings.
parameters_table	One row per runner option: name, value used, and whether it was the default.
provenance_record	Parameters, input and executable identities written to PROVENANCE.json.
sha256	Stream file bytes into a SHA-256 digest for the run's provenance.

7. Diagnostics and comparisons

fasta_lake._ckg_worker

Function	Purpose
_json_for_script	Serialize data safely for a JavaScript string literal in an HTML script.
component_layout	Keep disconnected membership components readable in a deterministic grid.
remove_unused_bootstrap	Remove PyVis's unused remote Bootstrap assets from its inline template.
render	Plot reported membership and topological communities without re-inferring proteins.

fasta_lake.benchmark

Function	Purpose
_is_entrapment_accession	One rule for both loaders: an entrapment record carries ENTRAP or SHUFFLED
_pearson	Pearson correlation coefficient.
build_gene_map	Build accession → gene name map from a FASTA file.
compare	Compare FastaLake search results against a baseline.
is_real_gene_symbol	Check if a gene name is a real HGNC/MGI symbol, not an accession fallback.
load_diann_report	Load a DIA-NN report.tsv and extract peptides, genes, protein groups.
load_sage_report	Load a SAGE results.sage.tsv and extract peptides, genes, protein groups.
print_benchmark	Pretty-print benchmark results.

fasta_lake.canonical_comparison

Function	Purpose
_load_diann_gene_peptides	Load DIA-NN report: gene → {peptides, intensity}.
classify_losses	Classify every gene lost from canonical → FastaLake.
print_loss_report	Print a detailed loss classification report.

fasta_lake.diagnose

Function	Purpose
calibration_curve	Compute empirical FDP vs nominal q-value curve across samples.
calibration_curve.target_db_size_fn	Supply the historical 75,000-protein fallback when no size callback exists.
outlier_samples	Identify samples with FDP > mean + z*std (outliers).
per_sample_fdp_at_q	Compute per-sample PSM- and protein-level FDP at a given q threshold.
write_report	Write calibration JSON/CSV and outlier JSON into the requested directory.

fasta_lake.entrapment

Function	Purpose
_validate_counts	Reject negative counts, non-integers and booleans before FDP accounting.
estimate_fdp	Estimate False Discovery Proportion using entrapment hits.
estimate_fdp_paired	Wen 2025 Eq 4 paired FDP estimator — a tighter valid upper bound.
generate_noble_paired	Noble paired entrapment: split proteins into target and entrapment sets.
generate_shuffled_entrapment	Generate shuffled entrapment proteins from source sequences.
load_entrapment_fasta	Load user-supplied entrapment proteins from a FASTA file.
prepare_entrapment	Prepare entrapment proteins based on configuration.
validate_entrapment_fdr	Validate FDR calibration using entrapment analysis.

fasta_lake.entrapment_classes

Function	Purpose
class_names	Registered class names, preserving the historical display order.
EntrapmentClass.as_metadata	Serialisable metadata for embedding in an FDP report.
get_class	Look up an entrapment class by name.

fasta_lake.entrapment_stages

Function	Purpose
EntrapmentStage.as_metadata	Serialisable metadata for embedding in a manifest or FDP record.
get_stage	Look up a stage, accepting aliases.
normalize_stage	Map an accepted spelling onto a canonical stage name.
stages_comparable	True only when two stages are the same injection point.

fasta_lake.entrapment_workflow

Function	Purpose
_config_class_name	Map an :class:EntrapmentConfig onto a registered class name.
_find_search_db	Return the first sorted matching search database, or None if absent.
_reconcile	Prefer an explicit value, but never let it silently contradict a manifest.
_sha256_file	SHA-256 of a file, streamed.
bootstrap_median_ci	Seeded percentile bootstrap CI on the median.
classify_psms	Classify accepted PSMs into target / entrapment / shared.
compute_fdp	Compute one FDP record for a (dataset, class, stage) triple.
compute_fdp._governing_manifest	Find the nearest governing injection manifest, with a single-manifest fallback.
conserved_peptide_scan	Test entrapment-attributed peptides for occurrence in the target space.
conserved_peptide_scan.norm	Apply I/L equivalence only when requested for this diagnostic scan.
ConservedScan.control_rate	Fraction of reversed entrapment peptides found -- should be ~0.
ConservedScan.rate	Fraction of entrapment peptides also present in the target space.
count_fasta_headers	Count proteins in a FASTA by counting header lines only.
detect_prefixes	Report the entrapment-like prefixes actually present in a FASTA.
expected_results_subdir	The per-sample subdirectory the run templates write for an entrapment class.
fdp_estimates	Compute every FDP estimator, returning None where undefined.
find_sample_results	Find (sample_id, results_tsv) under results_dir.
generate_entrapment_fasta	Write an entrapment FASTA for one entrapment class.
inject_entrapment	Concatenate entrapment into a database and record what was done.
iter_fasta	Stream (header, sequence) pairs from a FASTA file.
load_manifests	Load entrapment manifests, refusing to mix injection stages or classes.
partition_counts	Return (n_target, n_entrapment) protein counts for a FASTA.
prepare_from_config	Honour entrapment.enabled in a FastaLake JSON config.
shuffle_sequence	Shuffle a sequence, optionally holding K/R residues in place.
stage_measures	One-line statement of what an FDP at this injection stage estimates.
strip_modifications	Reduce a modified peptide string to bare uppercase residues.
summarize	n, median, IQR and a seeded bootstrap CI for a list of per-sample values.
verify_prefix_matches	Assert the configured prefix finds the entrapment partition that is declared.
write_conserved_report	Write the conserved peptides and their target proteins to TSV.
write_fdp_reports	Write the per-sample TSV, the (dataset, class, stage) record, and conserved peptides.

fasta_lake.study_annotation

Function	Purpose
annotate_study	Write study_group_annotation.tsv and annotated_study_group_matrix.tsv.
describe	Summarise parsed headers; distinct values are joined with ;.
fasta_headers	Read header lines for the wanted accessions from FASTA files.
load_header_sidecar	Map each emitted lake accession to its original source headers.
searched_fastas	Return the distinct FASTA files named by each acquisition's Sage record.

fasta_lake.tune

Function	Purpose
apply_filter	Count target / decoy / entrapment PSMs under a filter.
compute_fdp_combined	Noble 2025 combined-method FDP as percentage; None when undefined.
default_filter_grid	Standard grid. len × q × score cartesian product.
find_sample_results	Yield (sample_id, entrap_type, results.sage.tsv path) for each sample.
parse_tsv	Parse required Sage fields for the historical spectrum-q tuning diagnostic.
tune	Tune parameters by post-hoc filter sweep.
tune.target_db_size_fn	Supply the historical 75,000-protein fallback when no size callback exists.
write_reports	Write tuning CSV, recommended settings and supporting reports.