API Reference
Main API Functions
These are the primary functions for running EFDR analyses:
EntrapmentAnalyses.run_efdr_analysis
— Functionrun_efdr_analysis(parquet_files::Vector{String}, library_path::String; kwargs...)
Run empirical FDR analysis at the precursor level.
The function modifies the results DataFrame by adding pairing information columns:
is_original
: Boolean indicating if peptide is original (true) or entrapment (false)pair_id
: Integer ID linking original/entrapment pairsentrap_label
: Integer label (0=original, 1=entrapment) for EFDRcomplement_score
: Plex-specific score of the paired peptidecomplement_indices
: Deprecated column for backward compatibility
Arguments
parquet_files
: Vector of paths to Parquet files with PSM resultslibrary_path
: Path to TSV file with spectral library
Keyword Arguments
output_dir
: Output directory (default: "efdr_output")score_col
: Score column name (default: :PredVal)global_qval_threshold
: Global q-value filter threshold (default: 1.0 = no filter)local_qval_threshold
: Local q-value filter threshold (default: 0.05)r_lib
: Library to real entrapment ratio (default: 1.0)show_progress
: Show progress bars (default: true)
Returns
- DataFrame with EFDR columns added
EntrapmentAnalyses.run_protein_efdr_analysis
— Functionrun_protein_efdr_analysis(parquet_files::Vector{String}, library_path::String; kwargs...)
Run empirical FDR analysis at the protein level following the notebook implementation.
The function modifies the protein DataFrame by adding pairing information columns:
is_original
: Boolean indicating if protein is original (true) or entrapment (false)pair_id
: Integer ID linking original/entrapment pairsentrap_label
: Integer label (0=original, 1=entrapment) for EFDRcomplement_score
: Plex-specific score of the paired proteincomplement_indices
: Deprecated column for backward compatibility
Arguments
parquet_files
: Vector of paths to Parquet files with PSM resultslibrary_path
: Path to TSV file with spectral library
Keyword Arguments
output_dir
: Output directory (default: "efdr_output")score_col
: Score column name (default: :PredVal)global_qval_threshold
: Global q-value filter threshold (default: 1.0 = no filter)local_qval_threshold
: Local q-value filter threshold (default: 0.05)r_lib
: Library to real entrapment ratio (default: 1.0)show_progress
: Show progress bars (default: true)
Returns
- DataFrame with protein-level EFDR analysis
Data Loading
Functions for loading input data:
EntrapmentAnalyses.load_parquet
— Functionload_parquet(filepath::String)
Load a single Parquet file containing PSM results.
Arguments
filepath
: Path to the Parquet file
Returns
- DataFrame with PSM results
Missing docstring for load_spectral_library
. Check Documenter's build log for details.
Analysis Functions
Functions for different types of analyses:
Missing docstring for analyze_combined_efdr
. Check Documenter's build log for details.
Missing docstring for analyze_paired_efdr
. Check Documenter's build log for details.
EFDR Calculation
Core EFDR calculation method:
Q-value Calculation
Functions for q-value computation:
EntrapmentAnalyses.calculate_qvalues!
— Functioncalculate_qvalues!(df::AbstractDataFrame; score_col=:PredVal, decoy_col=:decoy, sort_df=true)
Calculate local q-values and add to DataFrame.
Arguments
df
: DataFrame to processscore_col
: Score column namedecoy_col
: Decoy column namesort_df
: Whether to sort the DataFrame (default: true)
EntrapmentAnalyses.calculate_qvalues_per_file!
— Functioncalculate_qvalues_per_file!(df::AbstractDataFrame; score_col=:PredVal, file_col=:file_name)
Calculate q-values separately for each file in the dataframe. Adds :localqvalue and :globalqvalue columns.
Arguments
df
: DataFrame with PSM resultsscore_col
: Score column name (default: :PredVal)file_col
: File identifier column (default: :file_name)
EntrapmentAnalyses.calculate_global_qvalues!
— Functioncalculate_global_qvalues!(df::AbstractDataFrame; score_col=:PredVal)
Calculate global q-values (best per precursor). Adds :global_qvalue column to the dataframe.
EntrapmentAnalyses.monotonize!
— Functionmonotonize!(values::AbstractVector{T}) where T<:AbstractFloat
Ensure FDR values are monotonically non-decreasing. Works in-place by traversing backwards through sorted results.
Algorithm
Starting from the end (worst scores), ensures each FDR is at least as large as the FDR of better-scoring results.
monotonize!(values::AbstractVector{Union{Missing, T}}) where T<:AbstractFloat
Handle missing values in monotonization.
Pairing System
Functions for computing peptide pairings:
EntrapmentAnalyses.compute_pairing_vectors!
— Functioncompute_pairing_vectors!(library_df::DataFrame, results_df::DataFrame; kwargs...)
Add plex-aware pairing information directly to the results DataFrame.
Modifies results_df
by adding the following columns:
:is_original
- Bool: true if peptide is original, false if entrapment:pair_id
- Int: ID linking original/entrapment pairs from library:entrap_label
- Int: 0 for original, 1 for entrapment (used in EFDR):complement_score
- Float32: plex & file-specific score of paired peptide (-1 if no pair):complement_indices
- Int: deprecated, always -1 (kept for compatibility)
The complement scores respect both file and plex boundaries, meaning the same peptide in different plexes can have different complement scores.
Arguments
library_df
: Library DataFrame with entrapment pairsresults_df
: Results DataFrame to modify (must have file_name and channel columns)
Keyword Arguments
lib_seq_col
: Library sequence column (default: :PeptideSequence)lib_charge_col
: Library charge column (default: :PrecursorCharge)lib_entrap_col
: Library entrapment group column (default: :EntrapmentGroupId)lib_pair_col
: Library pair ID column (default: :PrecursorIdx)results_seq_col
: Results sequence column (default: :stripped_seq)results_charge_col
: Results charge column (default: :z)channel_col
: Channel/plex column (default: :channel)score_col
: Score column (default: :PredVal)file_col
: File name column (default: :file_name)show_progress
: Show progress bars (default: true)
Returns
- Modified
results_df
with new columns added
Visualization
Functions for generating plots and reports:
Missing docstring for plot_efdr_comparison
. Check Documenter's build log for details.
Missing docstring for plot_protein_comparison
. Check Documenter's build log for details.
EntrapmentAnalyses.plot_combined_efdr
— Functionplot_combined_efdr(df::DataFrame; kwargs...)
Create a plot showing only the combined EFDR results.
Arguments
df
: DataFrame with EFDR resultsoutput_path
: Output file path (default: "combined_efdr.pdf")fdr_col
: FDR column name (default: :local_qvalue)efdr_col
: EFDR column name (default: :combinedentrapmentfdr)
EntrapmentAnalyses.plot_paired_efdr
— Functionplot_paired_efdr(df::DataFrame; kwargs...)
Create a plot showing only the paired EFDR results.
Arguments
df
: DataFrame with EFDR resultsoutput_path
: Output file path (default: "paired_efdr.pdf")fdr_col
: FDR column name (default: :local_qvalue)efdr_col
: EFDR column name (default: :pairedentrapmentfdr)
EntrapmentAnalyses.plot_efdr_comparison_both_methods
— Functionplot_efdr_comparison_both_methods(df::DataFrame; kwargs...)
Create a comparison plot showing both combined and paired EFDR methods.
Arguments
df
: DataFrame with both combined and paired EFDR resultsoutput_path
: Output file path (default: "efdrcomparisonboth_methods.pdf")fdr_col
: FDR column name (default: :local_qvalue)combined_efdr_col
: Combined EFDR column name (default: :combinedentrapmentfdr)paired_efdr_col
: Paired EFDR column name (default: :pairedentrapmentfdr)
EntrapmentAnalyses.generate_analysis_report
— Functiongenerate_analysis_report(df::DataFrame, output_dir::String; kwargs...)
Generate a markdown report with embedded plots and analysis summary.
Arguments
df
: DataFrame with EFDR resultsoutput_dir
: Directory to save report and plotspaired_df
: Optional DataFrame with paired EFDR results (if calculated separately)
Type Definitions
Key types used throughout the package:
Index
EntrapmentAnalyses.calculate_global_qvalues!
EntrapmentAnalyses.calculate_qvalues!
EntrapmentAnalyses.calculate_qvalues_per_file!
EntrapmentAnalyses.compute_pairing_vectors!
EntrapmentAnalyses.generate_analysis_report
EntrapmentAnalyses.load_parquet
EntrapmentAnalyses.monotonize!
EntrapmentAnalyses.plot_combined_efdr
EntrapmentAnalyses.plot_efdr_comparison_both_methods
EntrapmentAnalyses.plot_paired_efdr
EntrapmentAnalyses.run_efdr_analysis
EntrapmentAnalyses.run_protein_efdr_analysis