Check that the BPP command-line tools are installed and new enough.

Call this FIRST in every session, before any other tool. It runs <tool> --version for bpp-seqs, bpp-tree, bpp-lint, bpp-docs and bpp.

Output:

• ready: true only when every tool is found and new enough AND a project directory is set. If false, read problems and help the user fix them before doing anything else; tell them the exact install_hint command.

• tools.<name>: found, path, version, minimum_version, ok, and problem / install_hint when something is wrong. Most tools are installed by the user running bpp-mcp install-tools in a terminal (no root needed); you cannot run it for them.

• project_root: the only directory the tools can read or write. Every path you pass to other tools is relative to it. If it is null, no project is set: ask the user which project folder to use and call set_project (if available), or explain that the host configuration must set BPP_MCP_ROOT.

Inspect the user's data files without changing anything (bpp-seqs --dry-run).

Call after check_environment, on whatever the user has: aligned loci (FASTA/PHYLIP/NEXUS, one or many per file), BAM/CRAM, gVCF, BED, a reference FASTA, and the Imap (sample -> species table). File types are detected from content. files may contain glob patterns relative to the project, e.g. ["loci/*.fasta"].

Read in the report:

• workflow (e.g. fasta2bpp) and ready_to_run: whether convert_data can run with these inputs.

• missing[]: inputs still needed (often the Imap). Ask the user for them.

• cross_validation.issues: mismatches between files, e.g. samples in the data but not the Imap. Explain them to the user before converting.

• files_provided[]: per-file type and counts; server.file_types counts the types. Next: convert_data with the same files and Imap.

Convert the inspected data into BPP input files (bpp-seqs).

Writes PREFIX.txt (the BPP seqfile), PREFIX.imap, PREFIX.stats.tsv and PREFIX.loci.tsv, where PREFIX is out_prefix relative to the project. Use the same files (globs allowed) and imap as inspect_data.

Options, all passed to bpp-seqs unchanged:

• phasing (BAM/CRAM and gVCF input only): iupac | split | haploid | vcf. Ask the user whether their diploid data are phased; for vcf also give phased_vcf. It does not apply to alignments.

• reference: designate the reference FASTA explicitly.

• Locus filters (bpp-seqs defaults apply when omitted): min_length, max_missing, min_snps, keep_invariant; read-based calling: min_bq, min_mq, min_dp, het_freq.

• overwrite: existing outputs are refused unless true. Ask the user first.

Read in the report: summary.n_loci_passed (also server.nloci) is the nloci value for make_control_file; summary.failure_reasons and loci[] say which loci were dropped and why; output_files names the files written. Tell the user how many loci passed. Next: build_species_tree.

Make a BED file of candidate loci by tiling a genome into windows (bpp-seqs windows).

Use when the user has BAM/CRAM or gVCF data but no BED file saying which regions are the loci (inspect_data then lists a BED under missing). input is anything holding chromosome names and lengths: the reference FASTA, a BAM/CRAM or a VCF/gVCF. out is the BED file to write; pass it to inspect_data and convert_data with the other files.

Ask the user for the locus size and spacing; do not choose them yourself. All options are passed to bpp-seqs unchanged:

• window_size: locus length in bp. step: distance between window starts (default: window_size, so windows do not overlap).

• min_spacing: least distance in bp between kept loci on a chromosome.

• n_loci: sample this many windows at random (seed fixes the sample); omit to keep them all.

• include_chrom / exclude_chrom: chromosome names. autosomes_only: skip sex chromosomes, mitochondria and unplaced contigs (by name).

• skip_edges: drop this many bp at both ends of each chromosome.

• exclude_regions: a BED file of intervals to avoid.

• overwrite: an existing file is refused unless true. Ask the user.

Read in the report: n_windows_emitted (loci written) and the counts before it, which show what each filter removed. Next: inspect_data.

Write a new BPP seqfile holding a subset of the loci of an existing one (bpp-seqs extract).

Use to make a small data set for a trial run, or to drop or keep particular loci. seqfile is a PREFIX.txt from convert_data. Writes out_prefix.txt, plus .imap and .loci.tsv when the input has them next to it. The original files are not changed.

Selection (at least one; passed to bpp-seqs unchanged):

• first / last: the first or last N loci. range: 1-based positions such as "1-50" or "1-10,41-50". These three add together.

• loci: locus names. chrom: loci from this chromosome (needs the .loci.tsv). min_sites / max_sites: by alignment length.

• Different kinds of selection combine with AND. invert: keep the loci that do NOT match.

• imap: use this Imap instead of the one next to the seqfile.

• overwrite: existing outputs are refused unless true. Ask the user.

Read in the report: n_loci_input, n_loci_kept (also server.nloci: the nloci value for make_control_file with the new seqfile) and output_files. Next: make_control_file with the new seqfile, or set_keyword for seqfile and nloci on an existing control file.

Build the species (or guide) tree from a join formula (bpp-tree).

Writes PREFIX.stree (the species&tree block, with individual counts taken from the Imap, plus any migration block) and PREFIX.nwk. Pass PREFIX.stree to make_control_file as stree_file.

• joins: comma-separated joins, each 'X+Y' or 'X+Y=name', e.g. 'chimp+bonobo=pan, pan+human, gorilla+pan_human'. A label like A_B refers to the clade of A and B. Tip names are the Imap's species names. Ask the user for the tree (or guide tree for delimitation); do not invent one.

• migration (MSC-M): bands 'SRC->DST, ...'. Mutually exclusive with introgression. The control file then also needs a wprior.

• introgression (MSC-I): events 'DONOR->RECIP phi=0.1, ...'. The control file then also needs a phiprior. Look up those priors with lookup_docs; lint_control_file reports what is missing.

Read in the report: newick, taxa, species_counts, species_and_tree_block, and warnings (e.g. ROOT_AUTO_JOINED: two clades were joined at the root automatically) and errors. server.diagram is an ASCII drawing of the tree. ALWAYS show the user the diagram and ask them to confirm the topology before going on.

Read a species tree the user already has (bpp-tree --read).

Use instead of build_species_tree when the user has a tree file: a Newick (or extended Newick with introgression), a species&tree block, or an old control file containing one. Migration and introgression in the file are recovered too.

• imap: the Imap from convert_data; fills in the individual counts. Without it the block has '?' for the counts and cannot be used yet.

• out_prefix: also write PREFIX.stree and PREFIX.nwk, for make_control_file's stree_file. Give it together with imap.

Read in the report: status, newick, taxa, species_and_tree_block, individual_counts_filled, migration, introgression, warnings and errors. server.diagram is an ASCII drawing of the tree: ALWAYS show it to the user and ask them to confirm it is the tree they meant. server.stree_file is set when out_prefix was given.

Create a BPP control file (bpp-lint --template --suggest-priors).

Never write a control file yourself; use this, then lint_control_file.

• analysis: A00 = estimate parameters on a fixed species tree; A01 = estimate the species tree; A10 = species delimitation on a fixed guide tree; A11 = joint species delimitation and species tree. Ask the user, explaining the choices in plain language.

• seqfile, imapfile: from convert_data (PREFIX.txt, PREFIX.imap). stree_file: from build_species_tree (PREFIX.stree). nloci: from convert_data's server.nloci. out: the control file to write. Data paths are written relative to the control file's folder.

• phase: for unphased diploid data, one digit per species in species&tree order (look up 'phase' with lookup_docs and ask the user).

• thetaprior, tauprior: leave unset to use priors derived from the data (inverse-gamma, alpha = 3); set only if the user asks.

• nsample, burnin, sampfreq, seed: chain settings; template defaults apply when unset. Discuss chain length with the user.

• extra: any other keywords as {"keyword": "value"}, e.g. {"wprior": "...", "threads": "..."}. Each name is checked against the manual's keyword list. Look up the syntax with lookup_docs first.

• overwrite: an existing file is refused unless true. Ask the user.

Returns the file's text and path. server.workarounds_applied lists patches for known bpp-lint bugs. Next: lint_control_file.

Change one keyword in a control file, then lint the file again.

Use this for every edit to an existing control file; never edit one by hand. Look up the keyword's syntax with lookup_docs first, and ask the user before changing a scientific choice.

• keyword: a control-file keyword, checked against the manual's list.

• value: everything after the =, on one line, e.g. "200000" for nsample or "invgamma 3 0.002" for thetaprior.

The keyword's line is replaced where it stands (layout and comments are kept); a keyword the file does not have yet is added at the end. A value that spans several lines in the file (such as species&tree) is refused: remake the file with make_control_file instead.

Returns the lint_control_file result for the edited file, plus server.changed (keyword, old, new; old is null if it was unset). Read server.status as usual, and run smoke_test again once it is "valid".

Validate a control file (bpp-lint --json --check-priors) and check it against its data.

Call after make_control_file and after every change. Loop until server.status is "valid": fix each error (with set_keyword, or by remaking the file with make_control_file and the corrected arguments), then lint again.

Read in the result:

• server.status: "valid" only if bpp-lint reports no errors AND the temporary server.data_checks found none. Use this, not report.status.

• report.diagnostics[]: each has code, severity, message, suggestion, suggested_fix. Use explain_diagnostic(code) to explain one to the user.

• report.prior_check: priors compared with estimates from the data.

• server.data_checks.issues[] (temporary, until bpp-lint checks these itself): missing data files, nloci larger than the data, sequence tags with no Imap line, Imap species that differ from the tree, phase digit count, speciesdelimitation with the wrong number of arguments. A valid lint does not prove BPP will run: smoke_test next.

Bring a control file written for BPP 2.x/3.x up to current syntax (bpp-lint --diff / --fix).

For users who arrive with an old control file. Call first with apply=false: nothing is written, and server.upgrade.diff shows the changes bpp-lint can make by itself (renamed keywords, old value formats). Show the user the diff. Only after they agree, call again with apply=true: the file is rewritten in place and the original is kept as .bak.

Returns the lint_control_file result for the file as it now stands (after the rewrite when apply=true), plus server.upgrade:

• fixes_available: false means bpp-lint has nothing to rewrite.

• diff: unified diff of the automatic fixes.

• applied, and backup (the .bak file) when applied. Automatic fixes are only part of an upgrade: errors left in report.diagnostics need a decision from the user. Make those changes with set_keyword, then lint again until server.status is "valid".

The BPP manual's entry for one control-file keyword, quoted verbatim (bpp-docs).

Use this instead of your own knowledge whenever you state BPP syntax, defaults, allowed values or keyword dependencies, and quote it to the user. keyword is a control-file variable such as 'thetaprior', 'phase' or 'speciesdelimitation'.

Read in the report: found; syntax, values, default, dependencies, description, and text (the whole section). If found is false, use search_docs.

Ranked full-text search of the BPP manual (bpp-docs --search).

Use for concepts rather than single keywords, e.g. 'migration prior', 'unphased diploid', 'species delimitation algorithm'. Returns the best matching sections with heading, score and snippet. Follow up with lookup_docs for a keyword, and quote the manual to the user.

Long explanation of a bpp-lint diagnostic code, e.g. 'BPP101' or '101'.

Use it to explain a lint_control_file diagnostic to the user in plain language. Returns code and text.

Run BPP briefly to prove it accepts the control file and loads the data.

Call after lint_control_file reports server.status "valid". Runs a copy of the file with a short chain (nsample, burnin) in a scratch folder that is deleted afterwards, from the control file's folder (as the real run will be). The results are NOT an analysis; never report them as findings.

Read in the result:

• ok: true if BPP finished; false if it failed (see error_line, BPP's fatal message, and output_tail); null if still running at timeout_s without an error, which means BPP read the file and data and started the MCMC. Only when lint is valid AND ok is not false is the file ready. Then call run_command to tell the user how to run the full analysis.

How the user starts the full analysis themselves. Does NOT run BPP.

Call last, once lint_control_file reports server.status "valid" and smoke_test did not fail. This server never starts the real run, which can take hours or days; give the user the command to run in their own terminal or job script.

Read in the result:

• directory: the control file's folder (absolute). BPP must be started from it, because the data paths in the file are relative to it.

• command: the BPP command line, with the full path of the same bpp binary smoke_test used.

• shell: both as one line to paste into a terminal.

• jobname, threads: the file's current values (null if unset). Output files are named from jobname. Look up 'threads' with lookup_docs before advising on it, and change it with set_keyword.

• notes: what to tell the user about long runs and clusters.