docs: restructure documentation for kmer indexing and phylogeny theory

Reorganize the documentation structure to better separate kmer indexing logic from phylogenetic analysis methods. This involves moving several existing pages into new directories under `theory/kmer_indexing` and `theory/phylogeny`, updating navigation links across the site, and adding new content for VCF pseudo-alignment and specific phylogenetic models.

- Move `doc/index.html` to `doc/theory/kmer_indexing/minimizer_selection/index.html` to document minimizer selection logic.
- Move `doc/installation/index.html` to `doc/theory/phylogeny/kmer_based/kmer_set_distances/index.html` for whole k-mer set distance documentation.
- Move `doc/usage/dump/index.html` to `doc/theory/kmer_indexing/superkmers/index.html` to cover canonical super-kmers.
- Move `doc/usage/query/index.html` to `doc/theory/kmer_indexing/entropy_filter/index.html` for low-complexity kmer filtering details.
- Move `doc/theory/encoding/index.html` to `doc/theory/kmer_indexing/encoding/index.html` for DNA and kmer encoding specifics.
- Move `doc/theory/indexing_architecture/index.html` to `doc/theory/kmer_indexing/indexing_architecture/index.html` for partitioning and routing architecture.
- Move `doc/usage/query/index.html` (duplicate move noted in facts, likely referring to the query command usage or similar) to `doc/theory/phylogeny/snp_based/sankoff_model/index.html` for the 16-state Sankoff model.
- Move `doc/theory/minimizer_selection/index.html` to `doc/theory/phylogeny/snp_based/central_snp_model/index.html` for central-position SNP models and substitution corrections.
- Move `doc/theory/indexing_architecture/index.html` (duplicate move noted) to `doc/theory/phylogeny/snp_based/gamma_rate_heterogeneity/index.html` for gamma rate heterogeneity and automatic alpha estimation.
- Move `doc/theory/entropy_filter/index.html` to `doc/theory/phylogeny/snp_based/sampling_design/index.html` for entropy-biased sampling design.
- Move `doc/formats/index_layout/index.html` to `doc/formats/vcf/index.html` to document VCF pseudo-alignment output and structure.
- Add `doc/molecular-ecology-modified.csl` with a new XML style definition for Molecular Ecology Modified citations.
- Update `UserDocMD/formats/vcf.md` to clarify that `--vcf` implies `--pseudo-alignment`, requires `--n-sites`, and generates files alongside `--fasta`.
- Add three new BibTeX entries in `UserDocMD/references.bib` for Karlin (1997, 1995) and Bennett & Moran (2013).
- Update `UserDocMD/theory/kmer_indexing/kmers.md` to use binomial distribution for probability calculations and define k-mer sharing deviation.
- Clarify in `UserDocMD/theory/phylogeny/kmer_based/kmer_set_distances.md` that counts are used instead of presence/absence for $L^1$ distance.
- Update `UserDocMD/theory/phylogeny/snp_based/gamma_rate_heterogeneity.md` to attribute method-of-moments $\alpha$ estimation to obikmer, not Jin & Nei (1990).
- Update `UserDocMD/theory/phylogeny/snp_based/sampling_design.md` to redirect entropy sampling references to the correct phylo section.
- Add new options `--cpu-max`, `--output`, `--pair-balance`, `--sibling-stats`, `--family-overlap`, and `--shannon` to `UserDocMD/usage/phylo.md`.
- Mark SNP-based distance saving and session reuse as unavailable in `src/obikmer/src/cmd/phylo/args/distance.rs`.
This commit is contained in:
Eric Coissac committed 2026-11-19 17:47:59 +01:00
1 parent d78a6b4501
commit 33d7a59dd9
43 files changed
+25375 -1117

No files matched your search

+232
View File
@@ -857,3 +857,235 @@
doi = "10.1214/aop/1176996461",
issn = "0091-1798,2168-894X"
}
@ARTICLE{Karlin1997-lm,
title = "{Compositional differences within and between eukaryotic genomes}",
author = "Karlin, S and Mrázek, J",
journal = "Proceedings of the National Academy of Sciences of the United
States of America",
publisher = "Proceedings of the National Academy of Sciences",
volume = 94,
number = 19,
pages = "10227--10232",
abstract = "Eukaryotic genome similarity relationships are inferred using
sequence information derived from large aggregates of genomic
sequences. Comparisons within and between species sample
sequences are based on the profile of dinucleotide relative
abundance values (The profile is ρ* XY = f * XY / f * X f * Y for
all XY , where f * X denotes the frequency of the nucleotide X
and f * XY denotes the frequency of the dinucleotide XY , both
computed from the sequence concatenated with its inverted
complement). Previous studies with respect to prokaryotes and
this study document that profiles of different DNA sequence
samples (sample size ≥50 kb) from the same organism are generally
much more similar to each other than they are to profiles from
other organisms, and that closely related organisms generally
have more similar profiles than do distantly related organisms.
On this basis we refer to the collection {ρ* XY } as the genome
signature . This paper identifies ρ* XY extremes and compares
genome signature differences for a diverse range of eukaryotic
species. Interpretations on the mechanisms maintaining these
profile differences center on genome-wide replication, repair,
DNA structures, and context-dependent mutational biases. It is
also observed that mitochondrial genome signature differences
between species parallel the corresponding nuclear genome
signature differences despite large differences between
corresponding mitochondrial and nuclear signatures. The genome
signature differences also have implications for contrasts
between rodents and other mammals, and between monocot and dicot
plants, as well as providing evidence for similarities among
fungi and the diversity of protists.",
month = sep,
year = 1997,
url = "http://dx.doi.org/10.1073/pnas.94.19.10227",
doi = "10.1073/pnas.94.19.10227",
pmc = "PMC23344",
pmid = 9294192,
issn = "0027-8424,1091-6490",
language = "en"
}
@ARTICLE{Karlin1997-vm,
title = "{Compositional biases of bacterial genomes and evolutionary
implications}",
author = "Karlin, S and Mrázek, J and Campbell, A M",
journal = "Journal of Bacteriology",
publisher = "American Society for Microbiology",
volume = 179,
number = 12,
pages = "3899--3913",
abstract = "We compare and contrast genome-wide compositional biases and
distributions of short oligonucleotides across 15 diverse
prokaryotes that have substantial genomic sequence collections.
These include seven complete genomes (Escherichia coli,
Haemophilus influenzae, Mycoplasma genitalium, Mycoplasma
pneumoniae, Synechocystis sp. strain PCC6803, Methanococcus
jannaschii, and Pyrobaculum aerophilum). A key observation
concerns the constancy of the dinucleotide relative abundance
profiles over multiple 50-kb disjoint contigs within the same
genome. (The profile is rhoXY* = fXY*/fX*fY* for all XY, where
fX* denotes the frequency of the nucleotide X and fY* denotes the
frequency of the dinucleotide XY, both computed from the sequence
concatenated with its inverted complementary sequence.) On the
basis of this constancy, we refer to the collection [rhoXY*] as
the genome signature. We establish that the differences between
[rhoXY*] vectors of 50-kb sample contigs of different genomes
virtually always exceed the differences between those of the same
genomes. Various di- and tetranucleotide biases are identified.
In particular, we find that the dinucleotide CpG=CG is
underrepresented in many thermophiles (e.g., M. jannaschii,
Sulfolobus sp., and M. thermoautotrophicum) but overrepresented
in halobacteria. TA is broadly underrepresented in prokaryotes
and eukaryotes, but normal counts appear in Sulfolobus and P.
aerophilum sequences. More than for any other bacterial genome,
palindromic tetranucleotides are underrepresented in H.
influenzae. The M. jannaschii sequence is unprecedented in its
extreme underrepresentation of CTAG tetranucleotides and in the
anomalous distribution of CTAG sites around the genome.
Comparative analysis of numbers of long tetranucleotide
microsatellites distinguishes H. influenzae. Dinucleotide
relative abundance differences between bacterial sequences are
compared. For example, in these assessments of differences, the
cyanobacteria Synechocystis, Synechococcus, and Anabaena do not
form a coherent group and are as far from each other as general
gram-negative sequences are from general gram-positive sequences.
The difference of M. jannaschii from low-G+C gram-positive
proteobacteria is one-half of the difference from gram-negative
proteobacteria. Interpretations and hypotheses center on the role
of the genome signature in highlighting similarities and
dissimilarities across different classes of prokaryotic species,
possible mechanisms underlying the genome signature, the form and
level of genome compositional flux, the use of the genome
signature as a chronometer of molecular phylogeny, and
implications with respect to the three putative eubacterial,
archaeal, and eukaryote domains of life and to the origin and
early evolution of eukaryotes.",
month = jun,
year = 1997,
url = "http://dx.doi.org/10.1128/jb.179.12.3899-3913.1997",
doi = "10.1128/jb.179.12.3899-3913.1997",
pmc = "PMC179198",
pmid = 9190805,
issn = "0021-9193,1098-5530",
language = "en"
}
@ARTICLE{Karlin1995-lt,
title = "{Dinucleotide relative abundance extremes: a genomic signature}",
author = "Karlin, S and Burge, C",
journal = "Trends in Genetics: TIG",
publisher = "Elsevier BV",
volume = 11,
number = 7,
pages = "283--290",
abstract = "Early biochemical experiments established that the set of
dinucleotide odds ratios or 'general design' is a remarkably
stable property of the DNA of an organism, which is essentially
the same in protein-coding DNA, bulk genomic DNA, and in
different renaturation rate and density gradient fractions of
genomic DNA in many organisms. Analysis of currently available
genomic sequence data has extended these earlier results, showing
that the general designs of disjoint samples of a genome are
substantially more similar to each other than to those of
sequences from other organisms and that closely related organisms
have similar general designs. From this perspective, the set of
dinucleotide odds ratio (relative abundance) values constitute a
signature of each DNA genome, which can discriminate between
sequences from different organisms. Dinucleotide-odds ratio
values appear to reflect not only the chemistry of dinucleotide
stacking energies and base-step conformational preferences, but
also the species-specific properties of DNA modification,
replication and repair mechanisms.",
month = jul,
year = 1995,
url = "http://dx.doi.org/10.1016/s0168-9525(00)89076-9",
doi = "10.1016/s0168-9525(00)89076-9",
pmid = 7482779,
issn = "0168-9525,1362-4555",
language = "en"
}
@ARTICLE{Karlin1994-on,
title = "{Heterogeneity of genomes: measures and values}",
author = "Karlin, S and Ladunga, I and Blaisdell, B E",
journal = "Proceedings of the National Academy of Sciences of the United
States of America",
publisher = "Proceedings of the National Academy of Sciences",
volume = 91,
number = 26,
pages = "12837--12841",
abstract = "Genomic homogeneity is investigated for a broad base of DNA
sequences in terms of dinucleotide relative abundance distances
(abbreviated delta-distances) and of oligonucleotide
compositional extremes. It is shown that delta-distances between
different genomic sequences in the same species are low, only
about 2 or 3 times the distance found in random DNA, and are
generally smaller than the between-species delta-distances.
Extremes in short oligonucleotides include underrepresentation of
TpA and overrepresentation of GpC in most temperate bacteriophage
sequences; underrepresentation of CTAG in most eubacterial
genomes; underrepresentation of GATC in most bacteriophage; CpG
suppression in vertebrates, in all animal mitochondrial genomes,
and in many thermophilic bacterial sequences; and
overrepresentation of GpG/CpC in all animal mitochondrial sets
and chloroplast genomes. Interpretations center on DNA structures
(dinucleotide stacking energies, DNA curvature and superhelicity,
nucleosome organization), context-dependent mutational events,
methylation effects, and processes of replication and repair.",
month = dec,
year = 1994,
url = "http://dx.doi.org/10.1073/pnas.91.26.12837",
doi = "10.1073/pnas.91.26.12837",
pmc = "PMC45535",
pmid = 7809131,
issn = "0027-8424,1091-6490",
language = "en"
}
@ARTICLE{Bennett2013-cl,
title = "{Small, smaller, smallest: the origins and evolution of ancient
dual symbioses in a Phloem-feeding insect}",
author = "Bennett, Gordon M and Moran, Nancy A",
journal = "Genome Biology and Evolution",
publisher = "Oxford University Press (OUP)",
volume = 5,
number = 9,
pages = "1675--1688",
abstract = "Many insects rely on bacterial symbionts with tiny genomes
specialized for provisioning nutrients lacking in host diets.
Xylem sap and phloem sap are both deficient as insect diets, but
differ dramatically in nutrient content, potentially affecting
symbiont genome evolution. For sap-feeding insects, sequenced
symbiont genomes are available only for phloem-feeding examples
from the suborder Sternorrhyncha and xylem-feeding examples from
the suborder Auchenorrhyncha, confounding comparisons. We
sequenced genomes of the obligate symbionts, Sulcia muelleri and
Nasuia deltocephalinicola, of the phloem-feeding pest insect,
Macrosteles quadrilineatus (Auchenorrhyncha: Cicadellidae). Our
results reveal that Nasuia-ALF has the smallest bacterial genome
yet sequenced (112 kb), and that the Sulcia-ALF genome (190 kb)
is smaller than that of Sulcia in other insect lineages.
Together, these symbionts retain the capability to synthesize the
10 essential amino acids, as observed for several symbiont pairs
from xylem-feeding Auchenorrhyncha. Nasuia retains genes enabling
synthesis of two amino acids, DNA replication, transcription, and
translation. Both symbionts have lost genes underlying ATP
synthesis through oxidative phosphorylation, possibly as a
consequence of the enriched sugar content of phloem. Shared
genomic features, including reassignment of the UGA codon from
Stop to tryptophan, and phylogenetic results suggest that
Nasuia-ALF is most closely related to Zinderia, the
betaproteobacterial symbiont of spittlebugs. Thus,
Nasuia/Zinderia and Sulcia likely represent ancient associates
that have co-resided in hosts since the divergence of leafhoppers
and spittlebugs >200 Ma, and possibly since the origin of the
Auchenorrhyncha, >260 Ma.",
month = aug,
year = 2013,
url = "http://dx.doi.org/10.1093/gbe/evt118",
keywords = "Nasuia deltocephalinicola; Sulcia muelleri; gene loss; genome
evolution; leafhopper; nutritional symbioses",
doi = "10.1093/gbe/evt118",
pmc = "PMC3787670",
pmid = 23918810,
issn = "1759-6653",
language = "en"
}