Parameter Configuration

Pioneer uses JSON configuration files to control analysis. This guide explains the parameters for both SearchDIA and BuildSpecLib.

SearchDIA Configuration

Frequently Modified Parameters

Most parameters should not be changed, but the following may need adjustment.

• first_search.fragment_settings.min_score: The minimum score determines which fragments must match in the fragment-index search in order for the precursor to pass. Each precursor is awarded a score based on which fragments match the spectrum. The score assigned to each fragment depends on its intensity rank. The default scheme is 8,4,4,2,2,1,1. That is, if the 1st, 3rd, and 7th ranking fragments matched the spectrum, the precursor would be awarded a score of 8+4+1=13. If all 7 of the fragments matched, the precursor would be awarded a score of 22. For normal instrument settings on an Orbitrap or Astral mass analyzer, the mass tolerance is about +/- 5-15 ppm and 15 is a reasonable default score threshold. However, for instruments with less mass accuracy (Sciex ZenoTOF 7600 or different Orbitrap scan settings), the score threshold may need to be set higher, perhaps to 20. It may be worthwhile to test different values when searching data from a new instrument or sample type. In order to pass the first search, a precursor need only pass the threshold and score sufficiently well in at least one of the MS data files.

• first_search.fragment_settings.max_rank: Search against only the n'th most abundant fragment for each precursor. Including more fragments can improve performance but increase memory consumption, and the search could take longer. From experience, there are diminishing returns after 25-50 fragments.

• quant_search.fragment_settings.max_rank: See above

• quant_search.fragment_settings.n_isotopes: If searching with non-Altimeter libraries (not recommended), such as Prosit or UniSpec, this should be set to 1 as the second fragment isotopes will not be calculated accurately.

• acquisition.nce: This is the initial guess for the normalized collision energy that will best align the Altimeter Library with the empirical data. Altimeter values should agree with those from Thermo Instruments manufactured in Bremen Germany. If upon inspection of the quality control plots the initial guess is far from the estimated value, it might be possible to improve search results slightly by re-searching with a better initial guess.

• acquisition.quad_transmission.fit_from_data: Estimate the quad transmission function from the data. Otherwise defaults to symmetric, smooth function.

• optimization.machine_learning.max_psm_memory_mb: Memory budget (in MB) for PSMs held in memory during LightGBM training. Pioneer dynamically estimates how many PSMs fit within this budget based on the column sizes of the Arrow file. Default is 2000 MB.

• During LightGBM training, any missing feature values are replaced with the column median. If a column is entirely missing, the values are filled with zero of the appropriate type.

Global Parameters

Parameter Tuning Settings

First Search Parameters

First Search Filter Constants

The first search uses a hybrid filter to decide how many precursors to carry forward from each stage. These are hardcoded constants (not JSON-configurable) because they should rarely need adjustment.

Per-file pre-filter (applied per MS file before cross-run aggregation): keeps the largest of three counts:

• PSMs with PEP ≤ 0.95
• PSMs where cumulative decoy/target ratio ≤ PERFILE_QVALUE_THRESHOLD (0.50)
• PERFILE_MIN_PSMS (10,000, or all PSMs if fewer exist)

Global post-filter (applied after cross-run global PEP computation): keeps the largest of three counts:

• Precursors with global PEP ≤ global_pep_threshold (default 0.5, JSON-configurable)
• Precursors where cumulative decoy/target ratio ≤ GLOBAL_QVALUE_THRESHOLD (0.15)
• GLOBAL_MIN_PRECURSORS (50,000, or all precursors if fewer exist)

The hard minimum floors ensure sparse datasets (e.g. single-cell proteomics) always retain enough precursors for second-pass scoring, while the q-value floors prevent decoy contamination in large experiments.

Quantification Search Parameters

Acquisition Parameters

RT Alignment Parameters

Optimization Parameters

Deconvolution

The deconvolution parameters are split into ms1 and ms2 sub-objects for separate control over MS1 and MS2 deconvolution, plus shared iteration settings.

Machine Learning

Protein Inference Parameters

MaxLFQ Parameters

Output Parameters

Logging Parameters

Path Parameters

BuildSpecLib Configuration

FASTA Input and Regex Mapping

Pioneer supports flexible FASTA input through GetBuildLibParams:

Input Options

1. Single directory: Scans for all .fasta and .fasta.gz files
2. Single file: Directly uses the specified FASTA file
3. Mixed array: Any combination of directories and files

Regex Code Mapping

The regex patterns for parsing FASTA headers can be configured in three ways:

1. Single regex set for all files (default):

   GetBuildLibParams(out_dir, lib_name, [dir1, dir2, file1])
   # All FASTA files use the same default regex patterns

2. Custom single regex set:

   GetBuildLibParams(out_dir, lib_name, [dir1, file1],
       regex_codes = Dict(
           "accessions" => "^>(\\S+)",
           "genes" => "GN=(\\S+)",
           "proteins" => "\\s+(.+?)\\s+OS=",
           "organisms" => "OS=(.+?)\\s+GN="
       ))
   # All files use these custom patterns

3. Positional mapping (one regex set per input):

   GetBuildLibParams(out_dir, lib_name, [uniprot_dir, custom_file],
       regex_codes = [
           Dict("accessions" => "^\\w+\\|(\\w+)\\|", ...),  # For uniprot_dir files
           Dict("accessions" => "^>(\\S+)", ...)             # For custom_file
       ])

FASTA Digest Parameters

NCE Parameters

Library Parameters

Modification Parameters

Processing Parameters

Path Parameters