Utilities
The shared helpers of the repository, to check before writing a helper, wrapper, serializer, or test scaffold.
Diese Seite ist noch nicht übersetzt
Sie wird auf Englisch angezeigt. Einstellungstexte, Hilfetexte und die Befehlszeilenreferenz bleiben auf allen Seiten englisch.
Check repo utilities before writing helpers, wrappers, serializers, test scaffolding. The index below is updated on a best-effort basis, can get out of date.
- Library functions > project utilities > macros > local one-offs
- Verify a candidate in source (signature, behavior, existing call sites) before use
- Use
treetime-utilshelpers for ndarray, assertions, serialization, and I/O instead of hand-written loops, wrappers, or raw stdlib and third-party calls - Update this index when adding, moving, or removing a shared utility
treetime-utils index
Crate root: packages/treetime-utils/src/ (module list in lib.rs).
Errors (error)
- Macros:
make_error!(),make_report!(),make_internal_error!(),make_internal_report!() - Conversion:
report_to_string(),to_eyre_error()
Strings and formatting (fmt)
- Owned string literal:
o!() fmt::float:float_to_significant_digits(),float_to_digits(),float_to_exponential()(Cprintf%.Neform such as6.617e-02),float_to_power_of_ten()andfloat_to_power_of_ten_with_error()(display form with superscript exponent and Unicode minus, such as5.07 × 10⁻⁵and5.07 ± 0.31 × 10⁻⁵), extension traitFloatFormatExt(.to_significant_digits(),.to_decimal_digits(),.to_digits())fmt::string:quote(),quote_single(),truncate()withTruncateDirection,truncate_right_with_ellipsis(),name_list()(first names of a list and the count of the rest, for messages),counted()(a count with its noun in singular or plural)
Collections and iterators (collections, iterator)
- Vector macros:
vec_of_owned![],vec_u8![] collections::container:get_one(),get_exactly_one(),minmax()collections::manyzip:Manyzip(zip any number of iterators intoVecitems)iterator:iterator_intersection(),iterator_difference(), traitMeanByKey(.mean_by_key(), an error for an empty sequence and for a count that the key type cannot hold)- Literal maps and sets:
btreemap!{},btreeset!{}(workspace dependencymaplit) IndexSet,IndexMapoperations (.difference())
Ndarray (array)
array::ndarray:
- Deterministic argmax (Python parity):
argmax_first(); within a tolerance of the maximum, NaN ignored:argmax_first_within()(first index),argmax_all_within()(every index) - Scalar reductions:
max_or(),min_or(),is_max_above() - Elementwise:
minimum(),maximum(),clamp(),clamp_min(),clamp_max() - Math:
exp(),log(),cumsum_axis() - Creation and padding:
zeros() - 1D helpers:
first(),last(),reverse(),reverse_inplace(),sorted(),sort_inplace(),partition_point()(binary search on an owned array or a view, any layout accepted) - Matrix construction:
outer()
Other array modules:
array::softmax_with_log_norm:softmax_with_log_norm_inplace()(normalizes a mutable view in place and returns the log normalization)
Serialization adapters (adapters)
Use with #[deser(as = ...)]:
ArrayVec:Array1as a listArray2Rows:Array2as a list of rowsTrueOrNull: aboolwritten astrueor left out
Numerics (least_squares)
LineFit::least_squares(): ordinary least-squares line fit (slope,intercept)
Numeric conversions (cast)
Use these instead of as casts, which clippy::as_conversions rejects:
ToF64Exact(.to_f64_exact()): integer tof64; lossless throughf64::fromup to 32 bits, checked by a debug assertion to stay within 2^53 for 64-bit typesusize_to_u64(),u32_to_usize(): lossless widening, guarded by a compile-time width assertionf64_to_usize_saturating(): truncation toward zero with the saturation ofas(NaN and negatives give 0, values above the range giveusize::MAX)f64_to_i32_saturating(): the same fori32(NaN gives 0, values beyond the range givei32::MINori32::MAX), for pixel coordinatesf32tof64:f64::from;u8tochar:char::from; 128-entry ASCII tables:AsciiChar::table()oftreetime-primitives
Intervals (interval)
- Types:
Range,RangeCollection - Queries:
range_contains(),range_contains_iter() - Set operations:
range_union(),range_intersection(),range_difference(),range_complement(), plus_itervariants,interval_sets_union(),interval_sets_intersection() - Conversion:
to_interval_set(),to_interval_sets(),from_interval_set()
Dates (datetime)
- Parsing:
parse_date(),parse_date_with_formats(),parse_date_with_format(),parse_date_range(),parse_date_uncertain(),parse_datetime*(),DATE_FORMATS,DateParserOptions - Ranges:
DateRange(from_iso(),from_ymd(),mean()) - Year fractions:
date_to_year_fraction(),year_fraction_to_date(),year_fraction_to_datestring(),year_fraction_days_between(),date_range_to_year_fraction_range(),year_fraction_at_month_start()(the instant at the start of a calendar month, for date axes) - Conversion and formatting:
iso(),days_in_month(),date_from_iso(),date_format*()
I/O (io)
io::json:json_read_file(),json_read_str(),json_read(),json_write_file(),json_write_str(),json_write(),JsonPretty;json_value_read_str(),json_value_read_file(),to_json_value(),from_json_value()(conversion between deser types andserde_json::Value)io::file:read_file_with()andwrite_file_with()(open a path or-for standard input or output, decompress or compress by extension, add the path to errors once),open_file_or_stdin(),create_file_or_stdout(),FileWriter(finish()returns flush and compression errors),is_path_stdin(),is_path_stdout()io::fs:ensure_dir(),absolute_path(),extension(),read_file_to_string(),read_file_to_string_if_exists()(app state files:Nonewhen the file is missing)io::compression:Decompressor,Compressor,CompressionType,guess_compression_from_filepath(),remove_compression_ext(),COMPRESSION_EXTENSIONSio::console:is_tty()env:env_var_optional()
Concurrency and randomness (sync)
sync::random:get_random_number_generator(seed)(Xoshiro256++ from a requiredu64seed),random_choice(),random_choice_maybe(),random_remove()
Initialization (init)
init::global:global_init()(error report hook of tests and tools),setup_logger(level, colors),stderr_has_colors()(standard error is a terminal andNO_COLORis unset),install_panic_hook(colors)andinstall_error_hook(colors)(the report hooks of the CLI, without the location and environment sections)init::clap_styles:styles()init::cpu:require_cpu_features()(stop with a message and exit code 1 when the CPU lacks a feature the build enables, called first in the constructors of the binaries),cpu_has_build_features(),CPU_FEATURES_MESSAGEinit::openblas:get_openblas_info(),get_openblas_info_str()
Test assertions (testing)
Use these for readable ndarray diffs, float maps with tolerances, proptest failures without backtraces, and exact error messages.
- Scalar and generic:
pretty_assert_eq!(),pretty_assert_ulps_eq!(),pretty_assert_relative_eq!(),pretty_assert_abs_diff_eq!(),pretty_assert_neg_inf!(),assert_error!() - Maps:
pretty_assert_map_ulps_eq!(),pretty_assert_map_abs_diff_eq!(), traitMapLike(BTreeMap,HashMap,IndexMap) - Arrays:
pretty_assert_array_eq!(),pretty_assert_array_finite!(),pretty_assert_array_nonneg!(),pretty_assert_array_positive!(),pretty_assert_array_diag_abs!(),pretty_assert_array_offdiag_upper_bounded!() - Property:
prop_assert_{abs_diff,ulps,relative}_eq!(),prop_assert_array_{abs_diff,ulps,relative}_eq!(),prop_assert_map_{abs_diff,ulps,relative}_eq!().prop_assert_ulps_eq!()andprop_assert_relative_eq!()take a format message after the options, as the scalarpretty_assertions do, to name the oracle of the expected value:prop_assert_relative_eq!(expected, actual, max_relative = 1e-15, "direct derivative of the quadratic") - Property structural:
prop_assert_array_finite!(),prop_assert_array_nonneg!(),prop_assert_array_positive!(),prop_assert_array_upper_bounded!(),prop_assert_array_diag_abs!(),prop_assert_array_offdiag_nonneg!(),prop_assert_array_offdiag_positive!(),prop_assert_array_diag_nonpositive!() - Tolerances: the ulps and relative assertions compare without an absolute floor unless the call gives
epsilon, and the absolute-difference assertions requireepsilon, so a comparison of small values or of a value with 0 states its absolute tolerance at the call site.clippy.tomlbans the assertions and the comparison macros ofapprox(ulps_eq!,relative_eq!,abs_diff_eq!and their_neforms), whose defaultepsilon = f64::EPSILONaccepts any two values closer than about 2.2e-16. A comparison outside an assertion uses the rule of its domain (coordinates_coincide(),YAxisPolicy::same_value()) or a builder ofapprox(Ulps,Relative,AbsDiff) with an explicit.epsilon(..) - Also check existing support files in
__tests__/andpretty_assertions treetimecrate tests:RecordingLoginpackages/treetime/src/test_utils/progress.rs(aLogSinkthat keeps every message and run warning)
Other locations
packages/treetime-io/src/: one module per file format: Newick (nwk), Nexus (nex), FASTA, GFF, Graphviz, Auspice types, UShER MAT, tables (csvwithTableFormatandCsvWriter,dates_csv,discrete_states_csv), name lists (name_list), graph writing (graph). Entry points follow one naming scheme:<format>_read(reader)and<format>_write(writer)hold the format logic,<format>_read_file(path)and<format>_write_file(path)wrap them throughread_file_with()andwrite_file_with(), and a_strform exists only where production code needs a string.FastaWriterandCsvWriter::create()write records as they arrive and end withfinish(). PhyloXML is inpackages/util-phyloxml, not yet wired intotreetime-iopackages/app-output/src/table_output.rs:table_write_file(),table_create(),table_read_file()(CSV and TSV outputs, with theTableFormatof theirOutputSelection)packages/app-output/src/command_outputs.rs:CommandKind(outputs(), the output table of a command with aDefaultRuleper output;all_selectable(),default_outputs(),added_outputs()for theOutputSettingsof a run), the one owner of which outputs a command has and writes by defaultpackages/app-output/src/output_conditions.rs:OutputSettings(the settings of a run that decide which outputs exist),SequenceOutputs,NotReconstructed(setting()),OutputCondition(description(),requirement()), the errorsUnavailableOutput(an output that the run cannot write) andUnmetCondition(an output whose condition the run did not meet)packages/app-output/src/output_format.rs:table_format()(TSV or CSV from the file name, TSV for standard output),FileFormat::check()(reject an output file name whose extension the output cannot write, withUnsupportedExtension),ChartFormat::from_path()(SVG, PNG or PDF from the file name, SVG for standard output; the one owner of chart file formats)packages/app-output/src/dates_table.rs:write_dates_table_file()(the node dates table, with the 90% bounds when the run has them)packages/app-output/src/annotated_graph.rs:AnnotatedGraph(the struct of per-node facts that every tree, graph, and per-node table output reads; fact groupssequences,dates,traitsareOptions),AnnotatedTreeView::new()(checked tree handle of it, aTreeSchedule, required by the tree-based writers)packages/app-output/src/output_plan.rs:ResolvedOutputs::path()(planned path of a non-tree output),PlannedFilewithRequested(per-file flag or--output-all),output_unavailable()(error for a named output without data, debug-level skip otherwise),ResolvedOutputs::ensure_unique_with_expansion()(destination collision check for outputs expanded into several files),ResolvedOutputs::alignment_paths()andResolvedOutputs::alignment_tree_outputs()(the paths of a per-alignment output, by alignment number),TreeWriteKind::is_per_alignment()(a tree output written once per alignment file)packages/app-output/src/tree_output.rs:write_tree_outputs_per_alignment()(every per-alignment tree output of a run, one file per alignment, in the coordinates of that file)packages/app-commands/src/commands/shared/output_args.rs:OutputRequest(the destructured output settings of one command, which the conversion of its arguments binds field by field, so a parsed output flag that no code reads fails the lint;resolve()builds the output plan)packages/app-commands/src/commands/ancestral/aa_node_data.rs:cds_names()(the CDS names a command uses, from its settings: the names ofcds_selection, otherwise the CDS features of theannotationfile; the one owner of this rule for the plan check oftreetime pipelineand the inputs of a server run),cds_selection_names()(the names ofcds_selectionalone, read without files),cds_output_paths()(the per-CDS files of an--output-translationstemplate) andtranslation_path()(the file of one CDS from a--translationstemplate)packages/app-commands/src/commands/shared/run_paths.rs:RunPaths(the inputs and outputs of a run by setting and path role, with the translation output template kept apart from the other outputs):check_without_cds_names()(reject a run whose output path names one of its inputs, for every path without a CDS template, and a run that reads standard input twice; at argument conversion throughcheck_command_paths()),check_with_cds_names()(the same comparison after the translation input and output templates are expanded with the CDS names of the run; at argument conversion when--cds-selectionlists them, and in theancestralrun after the CDS selection),run_inputs(),run_outputs()andRunPath; the privateopened_path()resolves the existing part of a path through symbolic links before the comparisonpackages/app-cli/src/cli/v0_args.rs:rewrite_v0_args()with the table of TreeTime 0.x spellings (replace or drop a spelling whose meaning is unchanged, stop with the replacement for one whose meaning changed or that v1 removed), the one owner of 0.x spellingspackages/app-cli/src/cli/dry_run.rs:dry_run_text()(the--dry-runtext: the effective config as YAML with resolved paths, then the planned output files with their conditions), usingCommandArgs::planned_paths()(packages/app-commands/src/command.rs, the output paths a run plans to write, per output)packages/treetime-io/src/state_weights_csv.rs:state_weights_read_file()(the state weights table ofmugration --weights: state name and weight per row)packages/app-commands/src/commands/shared/metadata.rs:MetadataArgs(the--metadataflag),MetadataIdArgs(--metadata-id-columns,--metadata-delimiters), shared by every command that reads a metadata tablepackages/treetime-io/src/csv.rs:find_column()withColumnRule::{Exact, OneOf, Containing}(the column of an input table by an exact requested name, by the first of several candidate names, or by the leftmost header that contains a word; names are normalized like headers), the one owner of column lookup in input tablespackages/app-commands/src/commands/shared/sequence_inputs.rs:SequenceInputs(the sequence settings of a command:read()reads the alignments,read_partitions()reads them and resolves the partitions),read_tree_and_sources()(read the tree, every alignment and the partition plans of a sequence command),read_sequence_sources()(read each--alignmentfile as one source: apply gap filling, pair the records with leaves, complete missing leaves),ancestral_input()(build theAncestralInputfrom the tree and aSequenceInput)packages/app-commands/src/commands/shared/partition.rs:PartitionArgsandPartitionSpec(the--partitionflag and config key: one entry per partition withname,alignment,sites,model,model_params),partition_entries()(entries to corePartitionEntryvalues, with the model parameters parsed against each entry’s model),ConfigPartitions(the same resolution from a config value, for the app run checks),partition_argument_error()(a resolver error as the argument error of its settings)packages/app-commands/src/commands/shared/partition_by.rs:PartitionSchemeandRateCategoryRule(the values of--partition-byand--rate-category-rule),check_scheme_arguments()(the argument rules of the schemes),codon_position_entries(),gene_entries()andrate_category_entries()(partition entries of a scheme for the resolver),rate_category_buckets()andk_means_thresholds()(sites intoslow,mediumandfastby change count),codon_position()(codon position of a site from the strand and phase of its GFF3 segment)packages/treetime/src/partition/fitch/site_changes.rs:fitch_site_change_counts()(number of edges with a Fitch substitution at each site of one alignment)packages/treetime/src/partition/resolve.rs:resolve_partitions()(entries, alignment lengths, the default model and the alphabet toPartitionPlan { layout, model }values, with the repeated names),resolve_partition_layouts()(the site rules alone, givingPartitionLayout { number, name, alignment, columns }; prune calls only this step),check_model_alphabet()andmodel_alphabet()(a model against the alphabet of a run without alignments),partition_label()(partition <number> '<name>'in messages), the one owner of partition resolutionpackages/treetime/src/partition/sites.rs:SiteRange(site rangesa,a-b,a-b\k, 1-based;FromStr,Display,columns()giving 0-based columns; serialized as a string with a schema pattern);site_ranges_from_columns()(compact ranges that cover a set of 0-based columns exactly once)packages/treetime/src/partition/split.rs:SequenceInput { alignments, partitions }(the sequence input of the core pipelines: alignment sources and partition plans),SequenceInput::whole_alignments()(one plan per alignment with one model, for homoplasy and tests),split_alignments()(the node sequences of each partition from its columns; a whole alignment moves without a copy), the one owner of splitting alignments into partitionspackages/treetime/src/partition/assembly.rs:AlignmentLayout(whole for an alignment with one partition over all its columns, without per-site data,is_whole(); split otherwise,new();assemble_sequence(),assemble_ambiguity(),assemble_substitutions(),assemble_indels(),assemble_edge_mutations(),compose_indels(),split_indels(); split pieces carryInDel.split_from),alignment_groups()(the partitions of a run, given as pairs of an optionalPartitionLayoutand a length, grouped by alignment with theirAlignmentLayout; build the groups once per topology pass and pass&[AlignmentGroup]to each edge operation), the one owner of the mapping between partition and alignment coordinates (kb/algo/partition-assembly.md)packages/treetime/src/partition/alignment_sequences.rs:stream_alignment_sequences()(node sequences and mutations of one alignment: a whole alignment streams in one pass, a split alignment is assembled and emitted in preorder), the one owner of streaming per alignmentpackages/treetime/src/partition/marginal/sparse/alignment_indels.rs:sparse_alignment_groups(),assembled_edge_indels(),composed_edge_pieces(),store_edge_indels(),merge_sparse_edges()(assemble, compose and store the indels of sparse edges per alignment), the one owner of indel moves on sparse edgespackages/treetime/src/partition/marginal/reconstruction.rs:with_layout()onDenseReconstruction,SparseReconstructionandMarginalReconstruction,layout()onDenseReconstruction,SparseReconstructionandReconstructionRef(the layout of a reconstruction; a reconstruction without one covers its whole alignment);packages/treetime/src/partition/set.rs:PartitionSet::layouts()andlayouts_or_whole()(the layout of every partition as aCow, whole layouts filled in),PartitionSet::alignment_groups()(the alignment groups of the partitions of a set)packages/treetime/src/partition/result.rs:AlignmentResult(facts of one alignment file: number, path, alphabet, length, mask, indel rate, sequences),PartitionResult(facts of one partition: number, name, alignment, sites, model, log-likelihood),alignment_results()(the alignment results of a pipeline from its per-alignment outcomes)packages/treetime/src/optimize/partition_rates.rs:scale_rates_to_unit_mean()(divide the rates of partitions by their site-weighted mean; ancestral scales only μ with it,normalize_partition_rates()also rescales the branch lengths and indel rates)packages/treetime/src/optimize/gather.rs:gather_alignment_edge_indel_counts()(indel events per edge and alignment, assembled for split alignments, so an indel across partitions counts once)packages/treetime/src/gtr/get_gtr.rs:model_states()(the state characters of a sequence model in the order ofpiandW),ModelOutput { alignments, models }(the model document)packages/app-commands/src/commands/shared/ancestral_trees.rs:write_ancestral_trees()(every tree output and the augur node data of a run with reconstructed sequences and branch mutations)packages/treetime/src/homoplasy/classify.rs:classify_mutation()(substitution between canonical states, change involving an ambiguous character, or insertion and deletion), the one owner of this counting rulepackages/app-commands/src/commands/shared/gtr_output.rs:partition_models()(theModelOutputof a run from its partition and alignment results),write_gtr_output()(the--output-modelfile of a run, oroutput_unavailable()when no model was fitted)packages/treetime-graph/src/key_map.rs:NodeMap<V>andEdgeMap<V>(KeyMap<K, V>keyed byGraphNodeKeyorGraphEdgeKey), the map of per-node and per-edge values: a vector indexed by key, iterated in ascending key order asBTreeMapis, withentry(),retain(),keys(),Indexthat panics on a missing key,MapLikefor the map assertions, and thekeymap!{}literal; keepBTreeMaponly for maps where few nodes have an entry, because the vector holds a slot for every key of the graphpackages/treetime-primitives/src/ascii_table.rs:AsciiTable<T>(one value per ASCII character, indexed byAsciiChar, sized byAsciiChar::COUNT), the one owner of tables indexed by characterpackages/treetime/src/alphabet/char_slots.rs:CharSlots(Alphabet::char_slots(): the slot of each character of an alphabet, for per-character counts such asComposition)packages/treetime-graph/src/node_names.rs:NodeNames, the name of every node of a graph, kept next to the graph:NodeNames::from_input()(the reader names unnamed input nodesNODE_<n>in preorder, renames each later node of a repeated name to<name>_<k>, and reports the unnamed nodes and the repeated names),NodeNames::name_new_node()(every operation that creates a node names it with the next unusedNODE_<n>),names[key](the unique name as&str),NodeNames::pairing_name()(the input name of a renamed node, for matching data from other inputs), the one owner of node names; writers and messages read names and never make them uppackages/treetime-graph/src/pair_by_name.rs:pair_by_name()(pair input entries with candidate nodes by their input name: the first entry of a name wins, every node with that input name receives it; returns unmatched entries and repeated entry names),key_by_name()(node of each unique name, for names the user types), the one owner of name pairingpackages/treetime/src/progress.rs:RunWarning,RunWarningKindandLogSink::warning()(a typed warning of a run: the CLI and the run log show its message, the run record keeps it for the apps)packages/treetime/src/seq/alignment.rs:pair_leaf_sequences(),LeafSequences(alignment records paired with leaves, with the unmatched records for the common length and mask)packages/treetime/src/mugration/trait_pairing.rs:pair_trait_rows()returningTraitPairing(metadata trait rows paired with leaves, with the observed values, repeated names, and unmatched rows)packages/treetime/src/ancestral/attach.rs:warn_leaves_without_data()withLeafData(warnings for leaves without a sequence or a trait value, which the fit treats as fully ambiguous)packages/treetime/src/gtr/refinement.rs:refine_gtr()withGtrRefinement(iteration count, theInferGtrOptionsof each fit, the optional sampling-bias correction), the one GTR refinement loop, run by mugration on any partition that implementsTransitionCounts(packages/treetime/src/partition/marginal/shared/update.rs, the dense and discrete partitions);optimize_gtr_rate()(the rate step, anyMarginalPassespartition)packages/treetime/src/gtr/infer_gtr/common.rs:infer_gtr_from_counts()withInferGtrOptions(GTR fit from transition counts and dwell times),DEFAULT_PSEUDO_COUNT(the pseudo-count default of every GTR fit and ofmugration --pc)packages/treetime/src/alphabet/state_alphabet.rs:StateAlphabet::new()(sorted unique state names of a discrete trait with index lookup; rejects fewer than 2 states)packages/treetime/src/partition/marginal/discrete/state_posterior.rs:StatePosterior::new()(most likely state, profile, and entropy of one node), read by every trait writerpackages/treetime/src/partition/marginal/posterior_states.rs:most_likely_state()(the tie rule: first state within 1e-10 of the maximum),AmbiguityThresholdwithplausible_states()(the states of the ambiguity report), the one owner of state decisions over posteriors for traits and sequencespackages/treetime/src/seq/sink.rs:SeqSink::ambiguity()(the threshold a sink needs; the stream then computes the ambiguous sites of each emitted node),SeqItem::seq_with_ambiguity()(the sequence with the ambiguity codes)packages/app-output/src/ambiguity_outputs.rs:AmbiguityOutputs(threshold_for()an output that carries the ambiguity report,warn_unwritten());packages/app-commands/src/commands/shared/ambiguity.rs: the--ambiguity-thresholdand--ambiguity-outputssettings ofancestral,timetree, andmugration, resolved withresolve()packages/app-commands/src/commands/shared/argument_error.rs:argument_error(settings, message)(a usage error that names the settings at fault; the CLI exits with code 2, and the app marks the settings),ArgumentError;packages/app-commands/src/commands/shared/required.rs:missing_required_args()(the argument error of required flags that neither the command line nor a config file gives, with the flag names from clap), the one owner of argument errors after parsingpackages/app-commands/src/commands/shared/input_warnings.rs:warn_duplicate_names()(raise aRunWarningfor repeated names)packages/app-commands/src/commands/shared/tree_input.rs:read_input_tree(path, dialect, log)(read the input tree of a command in its Newick dialect and warn about repeated node names),TreeDialectArgs(the--newick-dialect <structure>,<annotations>setting of commands with a tree input, defaultclassic,beast), the one owner of the tree input dialectpackages/treetime-io/src/nwk.rs:graph_from_newick()(the one conversion from a Newick graph to a TreeTime graph; rejects a network node with more than one parent),TREE_DIALECT_DEFAULTpackages/app-commands/src/commands/shared/alignment.rs:pair_alignment()(pair FASTA records with leaves at a command input, with FASTA descriptions by node, and warn about repeated sequence names)packages/app-commands/src/commands/shared/dates_input.rs:read_input_dates()(read the dates of a metadata table, pair them with nodes, and warn about repeated rows)packages/treetime-graph/src/schedule.rs:GraphSchedule::new()(validates a rooted graph, also a DAG with several parents and roots, and owns its traversal order; the graph keeps the built index until its topology changes, so build a schedule where a pass needs it instead of passing one through APIs:preorder()with every node after all its parents,postorder()with every node after all its children,parents()andchildren()with edge keys,roots(),leaves(); errors name the offending node),require_tree()(one root and at most one parent per node; algorithms that need a tree call it at their start),into_tree()givingTreeSchedule(root(),parent(),children(),preorder()), the one owner of traversal order. Only the tree-only output writers takeTreeSchedule; the custom lintforbidden_itemrejects it in the production code oftreetimepackages/treetime-graph/src/schedule_scan.rs:GraphSchedule::scan_down()andGraphSchedule::scan_up()(parallel passes from the roots to the leaves and back: each step gets its node’s input and one message per parent or per child, in edge order, and returns its output and its message; no recursion, the first error wins, results do not depend on the thread count),GraphSchedule::join_parent_edges()(pair each node’s input with one value per parent edge),ScanOutputs(into_map(),split_parent_edges(),unwrap_shared()for outputs shared as messages),PerEdge<T>(SmallVecwith inline room for one value, so a tree allocates nothing per node), the one owner of parallel graph passes. A step runs no rayon parallelism of its own, because a waitingjoininside a step runs stolen work on top of its stack and makes stack use depend on the graphpackages/treetime/src/clock/divergence.rs:root_to_node_divergences()(preorder root-to-node sums with a caller-given edge length),root_to_node_divergences_where_known()(the same over aGraphSchedulethat is a tree,Nonebelow an edge without a length), the one owner of divergence arithmeticpackages/treetime-simulation/src/: generator of test data with a known truth:simulate_coalescent()(coalescent tree fromSampleBatchsampling times and aTcSchedule, givingSimulatedTreewith node dates and edge durations),TcSchedule(constant(),piecewise(),exponential()),SubstitutionModel(new(),random(),jc69(),f81()),evolve_sequences()(sequences along the tree,SimulatedSequences::leaf_records(),leaf_records()for any sequence map),evolve_sequences_at_site_rates()(each site evolves over the edge durations times its own rate) anddraw_site_rates()(the rate of each site drawn with equal probability from rate categories, such as the gamma categories ofGammaRates),disjoint_gap_events()andapply_gap_events()(deletions on branches drawn in proportion to their duration, inherited by every node below, never sharing or touching a site),observe_tips()withTipObservation(leaf sequences as sequenced: IUPAC codes drawn uniformly among the codes with the true base, and runs of N, a coarsening at random), branch lengthsexact()(expected substitutions per site),realized()(fraction of sites that differ between parent and child sequence, gap sites not counted),perturbed()(log-normal noise),FALSE_FAIL_RATE(the false-failure rate of one simulation test, split across its checks)packages/treetime-graph/src/clades.rs:graph_clade_keys()(the clade of every node as sorted tip ids),clade_keys()(the same over nodes in preorder),first_node_by_key()(node of each clade),TipIds(tip ids shared across graphs), for matching the nodes of two trees by cladepackages/treetime/src/test_utils/simulation.rs: adapters from the generator to the core:CaseSpec(simulate()gives aSimulatedCase),timetree_cell()andtimetree_cell_params()(the standard timetree case),arb_simulated_case()(proptest strategy), the input builderstimetree_input(),optimize_input(),ancestral_input(),exact_tip_dates(),simulated_sequence_source(),first_columns(),gtr_from_model(),match_internal_nodes()(true node to inferred node by clade),run_replicates()(seeded replicates in parallel), the statistical checksrecovery_check(),upper_recovery_check(),decrease_check(), andrequire_passed()(fail with every check’s summary)packages/treetime/src/test_utils/reference_log_z.rs:reference_log_z()withReferenceInput(independent oracle of the raw root log masslog_lh_timeof a fixed tree: per-cell quadrature on uniform grids at h, h/2, h/4 with Richardson extrapolation and an error estimate),BranchTime::from_likelihoods(),NodeFactors(no prior, or aCoalescentPrior);packages/treetime/src/test_utils/poisson_cherry.rs:PoissonCherry(closed-form log Z, root-age gamma posterior, rate slope of a two-tip tree)packages/treetime/src/test_utils/kingman.rs:kingman_neg_log_density()(Kingman coalescent density of node ages, polytomies as simultaneous mergers),pair_exposure(),node_ages_from_dates(),simulated_node_ages()packages/treetime/src/test_utils/rate_profile.rs:FrozenRateState::new()(branch distributions at the true rate and a point prior at the true node times of a simulated case),profile()andpoint()(TreeTime’s log Z over clock rates next toreference_log_z())packages/app-backend/src/app_paths.rs:app_root()(app folder of a local app,TREETIME_APP_DIR),AppPaths::resolve()(profile, runs, logs, and examples folders from theTREETIME_*_DIRvariables, thepaths:settings, and the app folder), the one owner of app folder resolutionpackages/app-backend/src/atomic_write.rs:write_atomically()(write through a temporary file in the same folder, then rename)packages/app-commands/src/config/resolve_paths.rs:resolve_config_paths()(rewrite relative input, input-template, and output paths of a config value to the folder of its config file, using thex-pathroles of the command schema;-, absolute paths, and empty strings stay),resolve_config_paths_where()(the same for the settings a predicate selects), the one owner of config path resolutionpackages/app-commands/src/examples_download.rs:examples_url()(URL ofexamples.zipof this build’s release),download_examples()(download with progress, unpack into an empty target folder through a private temporary folder);packages/app-commands/src/examples_unpack.rs:unpack_examples()withUnpackLimits(writes only regular files and folders of an archive inside the target, at paths built from checked names; refuses links, special files, duplicate names, mismatched headers, names that leave the folder or that Windows reserves, and archives over the entry or size limit), the one owner of unpacking downloaded archives;ExampleDownloadsinpackages/app-backend/src/examples_download.rs(one background download at a time for a local app)packages/app-backend/src/datasets.rs:DataIndex::new()(the index of the example data: every tracked file ofdata/outside hidden files and folders, the datasets with their input files, the example configs and pipelines), written todata/index.jsonbyjust data-reindex(generate-data-indexofpackages/app-cli), the one owner of example data discovery; every app reads example data only through itpackages/app-ui/build/example-data-vite.ts:exampleData()(the Vite plugin of both web apps that servesdata/index.jsonand its files in the dev server and copies them intodist/data/). Build code imports generated zod schemas from@neherlab/app-contracts/zod, because Vite leaves workspace imports of a config to Node, which cannot load the extensionless entry of the contracts packagepackages/app-backend/src/runs/lifecycle.rs:StartedRun::prepare(),compute_run(),PreparedRun::complete()(a run as prepare, compute, and complete steps around the serializableRunJobandRunOutcome), withtrait RunExecutorinpackages/app-backend/src/bridge/executor.rs(where the compute step runs:ThreadExecutorin the native apps, a job worker per run in web2), the one owner of the run lifecyclepackages/app-ui/src/i18n/locale.tsx(@neherlab/app-ui/i18n):m(the compiled Paraglide messages),LocaleProvider,useLocale(),locales,baseLocale; every message call passes the locale,m.<key>(params, { locale })packages/app-ui/src/chrome/:HeaderBar,ProductIdentity,ThemeCycleButton(withnextTheme()),SearchTrigger, the header parts of the app and the docs sitepackages/design/src/tokens/tokens.ts: the design tokens (BASE_COLORS,ALIAS_COLORSwith the chart roles,DATA_COLORS,CONTRAST_REQUIREMENTS,TYPEFACES,CORNERS,MOTION,resolveColor()), the one owner of colors, typefaces, and radii;packages/design/src/tokens/color.ts:cssColor(),hexColor(),hexPair()(a token as the hex pair of both themes, for Electron windows andtheme-colortags),rgbBytes(),contrastRatio()packages/design/src/ui/: the shared controls (@neherlab/design/ui/<name>), with the vendored shadcn/ui components listed inUPSTREAM.mdand the package’s ownwordmark(product and lab wordmarks),stat(a value with its uncertainty),description-list,meter,copy-button, anddata-table;packages/design/src/specimen/:DesignSpecimen, the specimen of the docs pagepackages/app-ui/src/settings/help.tsx:SettingSummary(label slot, flag, default),SettingHelp(help and “More” text as Markdown),defaultText(value, locale);packages/app-ui/src/settings/groups.ts:groupedSpecs()(settings by--helpgroup, without the catalog)packages/app-docs/src/lib/urls.ts:docsUrl()andassetUrl()(every link of the docs site, with the version base and the locale prefix),docsPath()andassetPath()for a given base, the one owner of docs URLspackages/app-docs/src/markdown/pipeline.ts:docsMarkdownProcessor()(the Markdown pipeline of the docs site: directives, callouts, steps, math, provided components, version and language URLs)packages/app-docs/src/markdown/provided-imports.tswithProvidedComponentsinpackages/app-docs/src/components/provided-components.ts: the components that docs pages use without an import, andIcon<Set><Name>icons;remarkProvidedComponents()adds their imports andclient:directives, the one owner of components in pagespackages/app-docs/src/lib/source.ts: the page tree of the docs site from the collectionsdocs(thedocs/folder) andgenerated, and the settings pages from the setting catalogpackages/app-docs/src/translations/translation-status.ts:translationStatus()andcontentHash()(missing, stale, and orphan translations ofdocs/,just docs-i18n-status)packages/app-ui/src/analysis/inputClaims.ts:claimInputs()(claim input settings before an asynchronous fetch or upload, so a later choice of the user wins);packages/app-ui/src/analysis/draftInputs.ts:applyDraftInputs()withassignInputs()of the draft store (assign inputs and release the uploads they replace), the owners of input choices in the analysis formpackages/app-commands/src/json_value.rs:JsonValue(a JSON value withoutnull) andSparseConfig(settings by key), the named JSON types for free-form fields of schema types; use them instead ofserde_json::Valuein a type that derivesJsonSchemapackages/app-commands/src/command_config.rs:CommandConfig(a command tagged with its parsed config; run records and pipeline steps carry it)packages/app-backend/src/config/choices.rs:setting_choices()(the settings of a command that the form shows as one choice, with the patch each option applies),active_choices()(the option a config selects, by the precedence the core uses)packages/treetime-schema/src/no_null.rs:NoNull(schema transform: anOptionfield is optional and never nullable, markedx-unset), part ofdraft2020_settings()inpackages/app-commands/src/config/schema.rs, which every project schema generator usespackages/treetime-distribution/src/distribution_ops/mass_profile.rs:MassProfile::new()andMassProfile::fractions()returningMassFractions(mass_between(),survival(),quantile(),survival_inverse(),density(x, side)), the mass model of a time distribution with its tail mass, the one owner of mass, quantile, survival and density queriespackages/treetime-grid/src/grid.rs:coordinates_coincide()(two time coordinates are the same point within 4 ulps of a scale),Grid::coincides()andGridFn::coincides()(the same at the largest magnitude of the grid), the one owner of coordinate comparisonpackages/treetime-grid/src/y_axis_policy.rs:YAxisPolicy::same_value()(two y values are the same probability: relatively for linear probabilities, with an absolute floor at 1 for negative log probabilities)packages/treetime-grid/src/grid_fn.rs:GridFn::hard_cell()(the power-law law of a cell next to a hard end),GridFn::hard_cell_fit_range()(the grid points that law is fitted from)packages/treetime-distribution/src/distribution_ops/edge_convolution.rs:convolve_forward_across_edge()andForwardConvolution::resolve_posterior()(forward message on the capped spacing that still resolves the posterior it forms),ResolvedForward::trim_posterior_to_mass()packages/treetime/src/timetree/max_posterior_region.rs:posterior_survival()(survival function of a posterior as linear pieces at fixed probability levelsSurvivalLevel),max_posterior_region()packages/treetime-ops/src/convolution.rs:FftConvolver(FFT buffers for one pair of operand lengths, reused by repeated convolutions such as the tilts of one distribution convolution),FftPlans(FFT plans by transform length, shared by the convolutions and threads of onetimetreerun),FftConvolver::overlap_sums()(the plain sums of products of every overlap, without trapezoid weights, for windows of longer operands),FftConvolver::overlap_sums_round_off()(a proven bound of the absolute round-off of every overlap sum of the power-of-two real FFT, from the operand norms, derived inkb/decisions/distribution-convolution-tails-by-exponential-tilting.md),rounding_gamma()(the rounding error factor γ_n = nu/(1 - nu) of n floating-point operations, for round-off bounds),convolve_direct_at()(one output sample by direct quadrature),convolve_direct_neg_log_at()(one output sample by direct quadrature in log space over an index range of its pairs, with the weights of the full sum, so that exact zeros stay+infand depths below the smallest double keep their value),trapezoid_weight()(the weight of one pair in the trapezoid sum of an output sample) and theConvolveAlgoimplementationsFftConvolve,DirectConvolve,NdarrayConvolve(convolution of two sampled functions, every algorithm by the trapezoid rule over each overlap), the one owner of convolution quadraturepackages/treetime-grid/src/max_grid_points.rs:MaxGridPoints(the grid point limit of time inference, validated betweenMaxGridPoints::MINandMaxGridPoints::MAX, the smaller ofusize::MAXand 2^53 - 1, so that every grid coordinate index converts tof64exactly),MaxGridPoints::point_count()(check a floating-point point count against the limit before any integer conversion or allocation; returnsGridPointLimitExceededabove it), the one owner of grid size checkspackages/app-backend/src/run_limits.rs:RunLimits::apply()(fill an unsetmax_grid_pointsof a run config from the desktop settings or the server option, and reject values above the server option), the one owner of global run limitspackages/app-commands/src/commands/shared/seed.rs:SeedArgs(the--seedflag of commands with a random step),SeedArgs::resolve()(one seed per run: the given one or a drawn one, logged when the run has a random step), the one owner of run seedspackages/app-commands/src/yaml.rs:yaml_read_str()(typed YAML read with setting paths in errors and YAML 1.1 boolean words),yaml_value_read_str()(YAML toserde_json::Value, rejects non-finite numbers),yaml_document(),yaml_text()(YAML output of JSON values through thesaphyremitter)packages/treetime/src/lib.rs: module list of the core library; the workspaceCargo.tomllists the cratespackages/treetime-openblas: the OpenBLAS link through pkg-config (build.rs, with the install commands of each platform in its error) and the declarations of theopenblas_get_*functions, whichinit::openblasoftreetime-utilsformatspackages/treetime-charts:register_chart_fonts()andCHART_FONT_FAMILY(IBM Plex Sans, also registered assans-serif;FALLBACK_FONT_FAMILYLato for the characters that Plex Sans lacks) infont.rs,svg_to_png(),svg_to_pdf()inconvert.rs, the one owner of chart fonts and SVG conversion;palette(generated from the design tokens byjust gen design:PAPER,INK,MUTED,GRID,AXIS,SERIES,FIT,FAULT),ticks(linear_ticks()with one number format per axis,date_ticks()at calendar months and years),text(text_width()as the SVG renderer measures it,draw_text()that draws a text in runs by the font that has each character,Weight),scale(LinearScalefrom data to pixels); compiled only for targets other than WebAssembly.encode_chart()inpackages/app-commands/src/rtt_chart/write.rswrites a chart in theChartFormatof its output file;RttChartData,RttFrameandRttSummaryinpackages/app-commands/src/rtt_chart/hold the points, the axis ranges with the fit and its extrapolation to the root, and the statistics texts that the image chart and the terminal chart sharedev/lib/env.sh: shared shell helpers for scripts indev/(load_env_file(),hash_files(),docker_cpu_budget(),docker_cpu_share()), and the one owner of quiet command output:run_quiet <context> <command...>(print nothing on success, and the context with the whole output of the command on failure or after a signal),docker_build_quiet <context> <buildx args...>(an image build throughrun_quietwith the plain log, streamed instead whenBUILDKIT_PROGRESSis set),print_failed_log <context> <log file>(the failure output of jobs that write their logs to files, such as parallel builds); tests indev/lib/__tests__/(just test-dev-sh)dev/lib/dist-flags.sh:export_dist_flags <binary|addon> [target](RUSTFLAGS and C flags of the shipped builds, with the static GCC unwinder for glibc binaries), the one owner of the shipped CPU flags, used bydev/cross/build, the dist, profiling, bench, and addon recipes,dev/prebuilt-libs-check, and the build record check ofdev/docker/files/install-image-librarieskb/algo/(algorithms, background) andkb/issues/(defects, traps): navigation aids, not source substitutes
Wrong vs correct
// WRONG - direct constructor noise for static test datalet traits = BTreeMap::from([ ("A".to_owned(), "usa".to_owned()), ("B".to_owned(), "?".to_owned()),]);
// CORRECT - use project's existing literalslet traits = btreemap! { o!("A") => o!("usa"), o!("B") => o!("?"),};// WRONG - raw serde_json call when repo helper existslet actual = serde_json::to_string_pretty(&node)?;
// CORRECT - use repository JSON helperlet actual = json_write_str(&node, JsonPretty(true))?;// WRONG - ad-hoc assertion functionfn assert_profiles_close(lhs: &Array1<f64>, rhs: &Array1<f64>) { assert!(lhs.iter().zip(rhs).all(|(a, b)| (a - b).abs() < 1e-10));}
// CORRECT - shared assertion macropretty_assert_abs_diff_eq!(lhs, rhs, epsilon = 1e-10);// WRONG - custom property assertion wrapperif !approx::ulps_eq!(lhs, rhs, max_ulps = 4) { return Err(TestCaseError::fail("mismatch"));}
// CORRECT - use shared proptest helperprop_assert_ulps_eq!(lhs, rhs, max_ulps = 4);// WRONG - local snapshot wrapper because the adapter was not checked#[derive(Serialize)]struct Snapshot { profile: Vec<f64>,}
// CORRECT - put the adapter on the real struct when that is the real contract#[derive(Serialize, Deserialize)]struct NodeData { #[deser(as = ArrayVec)] profile: Array1<f64>,}