Function Reference

convertBruker(path; output_dir = "") -> Vector{String}

Convert Bruker timsTOF diaPASEF .d bundles to .tdfs runs for SearchDIA. path is one .d folder or a folder containing them. Each bundle becomes <output_dir>/<name>.tdfs; output_dir defaults to tdfs_out next to the bundles. Uses the default slicing of TimsSlices (src/vendor/TimsSlices): slices every 0.0065 1/K0 with an IM Gaussian of 0.004325 1/K0 and an m/z Gaussian of 0.3125 ns of flight time, each converted to scans / TOF bins for the run (8 scans, 5 scans and 2.5 bins on the timsTOF Ultra), summed intensities, the 1,500 most intense centroids kept per MS2 slice, MS1 uncapped. Returns the .tdfs paths.

convertSciex(path; output_dir = "", zt_scan = nothing) -> Vector{String}

Convert SCIEX .wiff + .wiff.scan runs to .scxs runs for SearchDIA. path is one .wiff file or a folder containing them; each X.wiff needs its X.wiff.scan (or X.scan) beside it. Each run becomes <output_dir>/<name>.scxs; output_dir defaults to scxs_out next to the input. .wiff2-only runs are not supported (the .wiff2 format is encrypted); convert those with msConvert and convertMzML. Uses SciexWiff's default centroiding. Returns the .scxs paths.

zt_scan: whether the batch is ZT Scan DIA. The .wiff does not record the scan mode, so it is always asked: nothing prompts on an interactive terminal (default No) and is an error otherwise. ZT runs are written as <name>.zt.scxs with acquisition_type = zt_scan_dia in their metadata.

convertMzML(mzml_path::String; skip_scan_header::Bool=true, output_dir::String="", skip_existing::Bool=false, concurrent_files::Int=2)

Convert mzML mass spectrometry data files to Arrow IPC format.

Takes either a directory containing mzML files or a path to a single mzML file and converts them to Arrow format, preserving scan data including m/z arrays, intensity arrays, and scan metadata.

Arguments

• mzml_path::String: Path to either a directory containing mzML files or a path to a single mzML file
• skip_scan_header::Bool=true: When true, omits scan header information from the output to reduce file size
• output_dir::String="": Output directory for .arrow files. Defaults to <input_dir>/arrow_out
• skip_existing::Bool=false: When true, skip files whose existing .arrow output appears complete
• concurrent_files::Int=2: Number of mzML files to convert at the same time

Returns

nothing

Output

Creates Arrow (.arrow) files in the requested output directory with the same base filename as the input mzML files.

Requirements

Only centroided mzML is supported. Files containing profile-mode spectra are skipped during conversion.

Examples

# Convert all mzML files in a directory
convertMzML("path/to/mzml/files")

# Convert a single mzML file
convertMzML("path/to/single/file.mzML")

# Convert to a custom output directory
convertMzML("path/to/mzml/files", output_dir="path/to/arrow_out")

# Skip files that already have complete Arrow outputs
convertMzML("path/to/mzml/files", skip_existing=true)

# Include scan headers in output
convertMzML("path/to/mzml/files", skip_scan_header=false)

Notes

Each mzML file is converted to a corresponding Arrow IPC (.arrow) file in the output directory. Use it for SCIEX .wiff2 runs (convert them to mzML with msConvert first); .wiff runs can be converted directly with convertSciex.

ListSpecLibs(repo=HF_DEFAULT_REPO; as_json=false)

Print the libraries available in repo. The default, HF_DEFAULT_REPO, is the Hugging Face repository of prebuilt Pioneer libraries (nwamsley/altimeter_spectral_libraries).

as_json=true emits the machine-readable catalog the GUI parses; the default is a table for terminal use. Returns the catalog either way.

DownloadSpecLib(library, dest; repo=HF_DEFAULT_REPO, force=false)

Download the spectral library named library from repo into the directory dest, returning the path of the downloaded library.

The transfer stages into <name>.partial and is renamed only after every file has been fetched and checked against the repository's SHA256SUMS, so an interrupted download never leaves a directory that looks like a usable library. Re-running starts over: any leftover staging directory is discarded first, rather than resumed into.

GetBuildLibParams(out_dir::String, lib_name::String, fasta_inputs; 
                 params_path::Union{String, Missing} = missing,
                 regex_codes::Union{Missing, Dict, Vector} = missing,
                 simplified::Bool = true)

Creates a library building parameter configuration file with user-specified paths and FASTA files.

The function loads default parameters from either the simplified or full JSON template (from assets/example_config/) and creates a customized parameter file with the user's paths and automatically discovered FASTA files. All other parameters retain their default values and can be modified later.

Arguments:

• out_dir: Output directory path where the library will be built
• lib_name: Name for the spectral library (used for directory and file naming)
• fasta_inputs: FASTA file specification. Can be:
  • A single directory path (String) - searches for .fasta/.fasta.gz files
  • A single FASTA file path (String)
  • An array of directories and/or FASTA file paths
• params_path: Output path for the parameter file. Can be a directory (creates buildspeclib_params.json) or full file path. Defaults to buildspeclib_params.json in the current directory.
• regex_codes: Optional FASTA header regex patterns for protein annotation extraction. Can be:
  • A single Dict with keys: "accessions", "genes", "proteins", "organisms" (applied to all FASTA files)
  • A Vector of Dicts for positional mapping to fasta_inputs
  • If missing, uses default patterns from the template
• simplified: If true (default), uses simplified template with essential parameters only. If false, uses full template with all advanced library building options.

Returns:

• String: Path to the newly created library building parameters file

Templates used:

• Simplified: defaultBuildLibParamsSimplified.json (basic parameters)
• Full: defaultBuildLibParams.json (all advanced parameters)

The function automatically:

• Discovers FASTA files in specified directories
• Derives a proteome label for each FASTA file from its file name (fasta_names, reported as species in search results)
• Expands regex patterns to match the number of FASTA files found
• Validates that all specified paths exist and are accessible

Example:

# Create simplified parameter file with directory of FASTA files
output_path = GetBuildLibParams(
    "/path/to/output", 
    "my_library",
    "/path/to/fasta/directory"
)

# Create full parameter file with specific FASTA files and custom regex
output_path = GetBuildLibParams(
    "/path/to/output",
    "my_library", 
    ["/path/to/human.fasta", "/path/to/yeast.fasta"];
    params_path = "/custom/path/build_params.json",
    regex_codes = Dict("accessions" => raw"^sp\|(\w+)\|", "genes" => raw" GN=(\S+)"),
    simplified = false
)

BuildSpecLib(params_path::String)

Main function to build a spectral library from parameters. Executes a series of steps:

1. Parameter validation and directory setup
2. Fragment bound detection
3. Retention time prediction (optional)
4. Fragment prediction (optional)
5. Library index building

Parameters:

• params_path: Path to JSON configuration file containing library building parameters

Output:

• Generates a spectral library in the specified output directory
• Creates a detailed log file with timing and performance metrics
• Returns nothing

GetSearchParams(lib_path::String, ms_data_path::String, results_path::String; 
               params_path::Union{String, Missing} = missing,
               simplified::Bool = true)

Creates a search parameter configuration file with user-specified paths.

The function loads default parameters from either the simplified or full JSON template (from assets/example_config/) and creates a customized parameter file with the user's file paths. All other parameters retain their default values and can be modified later.

Arguments:

• lib_path: Path to the spectral library file (.poin)
• ms_data_path: Path to the MS data directory
• results_path: Path where search results will be stored
• params_path: Output path for the parameter file. Can be a directory (creates search_parameters.json) or full file path. Defaults to search_parameters.json in the current directory.
• simplified: If true (default), uses simplified template with essential parameters only. If false, uses full template with all advanced options.

Returns:

• String: Path to the newly created search parameters file

Templates used:

• Simplified: defaultSearchParamsSimplified.json (basic parameters)
• Full: defaultSearchParams.json (all advanced parameters)

Example:

# Create simplified parameter file
output_path = GetSearchParams(
    "/path/to/speclib.poin",
    "/path/to/ms/data/dir", 
    "/path/to/results/dir"
)

# Create full parameter file with custom output location
output_path = GetSearchParams(
    "/path/to/speclib.poin",
    "/path/to/ms/data/dir",
    "/path/to/results/dir";
    params_path = "/custom/path/my_params.json",
    simplified = false
)

SearchDIA(params_path::String)

Main entry point for the DIA (Data-Independent Acquisition) search workflow. Executes a series of SearchMethods and generates performance metrics.

Parameters:

• params_path: Path to JSON configuration file containing search parameters

Output:

• Long and wide-format tables (.arrow and .tsv) of precursor and protein-group identifications and quantities
• A per-run summary (run_summary.tsv), quality-control plots, and log files

Example:

julia> SearchDIA("/path/to/search_parameters.json")

If it does not already exist, SearchDIA creates the results directory given in the parameters file and writes:

results_dir/
├── config.json                  # the parameters used, with defaults filled in
├── pioneer_search_log.log       # console output
├── pioneer_search_report.txt    # summary report
├── pioneer_search_debug.log
├── pioneer_warnings.log
├── run_summary.tsv              # one row per run
├── precursors_long.arrow / .tsv
├── precursors_wide.arrow / .tsv
├── protein_groups_long.arrow / .tsv
├── protein_groups_wide.arrow / .tsv
└── qc_plots/
    ├── collision_energy_alignment/nce_alignment_plots.pdf
    ├── mass_error_plots/mass_error_plots.pdf
    ├── ms1_mass_error_plots/      # one plot per run
    ├── quad_transmission_model/quad_transmission_plots.pdf
    ├── rt_alignment_plots/rt_alignment_plots.pdf
    └── ion_mobility_model/ion_mobility_plots.pdf   # timsTOF data only