Changelog
Source:NEWS.md
hilldiv3 3.2.1
CRAN release: 2026-11-06
- Tests no longer open a PDF device on
/dev/null, which does not exist on Windows; they use a temporary file instead. No user-facing changes.
hilldiv3 3.2.0
- Multi-scale partitioning with
hierarchynow weights units linearly (Routledge/Tsallis-type), so every nested beta is at least one forq >= 0andalpha * prod(beta) = gammaholds exactly in unbalanced designs. Earlierp_u^qweights could give beta below one when units were unequal. Balanced equal-weight results are unchanged, but for unbalanced designs the nested alpha, betas and gamma atq != 1now differ from earlier development versions by a few per cent (and slightly atq = 1for functional diversity). -
hillpart()gainsweights("equal","abundance"or a numeric vector) for hierarchical designs, a referencedepthfor phylogenetic hierarchies (ultrametric trees) and a grid oftauvalues for functional hierarchies (one hierarchy pertau). -
hilldiss()andhillsim()return overlap metrics (S, C, U, V) per hierarchical transition, using a data-dependent effective number of units that keeps them in [0, 1].hillpair(hierarchy =, level =)compares units of a chosen level after weighted pooling of their samples. - Added
hillcontrib()to rank taxa or named sets by their additive contributions to pairwise or collective Hill dissimilarity. It supports neutral, phylogenetic and functional diversity and all four dissimilarity metrics. Collective comparisons can be run for named groups of samples. - Functional partitioning now handles an all-zero distance matrix through the shared functional-similarity kernel.
- Expanded the gut microbiome vignette with MAG power-sum shares and an illustrated example of MAG contributions to dissimilarity.
- Corrected the partitioning and dissimilarity vignette and the documentation of
hilldiss(),hillsim(),hillpair()andhillcontrib(): S and V are now described as turnover measures and U and C as overlap complements, C is one minus Morisita-Horn atq = 2,hillsim()documents its metrics as similarities, and the output descriptions and example names match what the functions return.
hilldiv3 3.1.1
CRAN release: 2026-10-16
- Documentation only: links in the README to
CONTRIBUTING.md,CODE_OF_CONDUCT.mdandCITATION.cffnow use absolute URLs, fixing the invalid file URI note raised by the CRAN incoming checks.
hilldiv3 3.1.0
- Added
hillshare()to allocate neutral, phylogenetic and functional Hill power-sum weight to individual taxa or named sets. Its first allocation method is"qpower"; empty samples have undefined (NA) shares. - Functional Hill numbers now handle all-zero distance matrices and empty samples consistently: identical taxa have diversity 1, and empty samples have diversity 0.
hilldiv3 3.0.1
- Added contributing guidelines (
CONTRIBUTING.md), a code of conduct, issue templates, citation metadata (CITATION.cff) and the full GPL-3 licence text, and a Journal of Open Source Software paper (paper/). -
Breaking: the
out = "matrix"form of the per-sample functions (hilldiv(),hillprof(),hilleven()) now returns samples in rows and diversity orders (q0,q1, …) in columns, instead of the previous orders-in-rows/samples-in-columns layout. This matches the usual observations-in-rows convention and joins cleanly with per-sample metadata. Code that indexed these matrices by["q0", ]should switch to[, "q0"](or transpose). The component/metric matrices fromhillpart(),hilldiss()andhillred()are unchanged. -
hilldiv()and friends now accept count tables whose first column holds taxa names: a leading non-numeric column is automatically promoted to row names (instead of failing with “Count data must be numeric”). Any other non-numeric column raises a clear error asking the user to fix the input. - Verbose output now reports the number of taxa and samples being analysed.
hilldiv3 3.0.0
CRAN release: 2026-10-06
First published on CRAN on 6 October 2026.
Complete redesign of the package built on a tested, isolated compute engine.
Architecture
- Math separated into an internal, unit-tested engine (
hill_alpha(),hill_partition(),hill_beta_to_dissim()); the user-facinghill*functions are thin wrappers around it. - Single validation/alignment layer (
prep_data()) that checks names withsetequal()and reorders data to match the tree/distance matrix, fixing the silent-misalignment behaviour of hilldiv2. - New
as_hill_input()adapter accepting matrices, data frames, tibbles,phyloseqandTreeSummarizedExperimentobjects. - Fast
ape-based post-order tree traversal replacesgeiger::tips().
New features
-
hillprof()— diversity profiles across a sweep of q values. -
hilleven()— evenness from Hill numbers. - Real
match_data()helper (previously only referenced in the docs). -
Tidy output by default.
hilldiv(),hillpart(),hilldiss(),hillsim(),hilleven(),hillprof()andhillred()now return long-formatdata.frames withprint(),plot()and (whenggplot2is installed)autoplot()methods. Passout = "matrix"for the legacy shape. -
Explicit
typeargument —type = c("auto", "neutral", "phylogenetic", "functional")on every entry point;"auto"keeps input-based detection, an explicit value asserts and validates the diversity type. -
hillpair()computes the type-specific structure once over all samples and reuses it per pair (no more full re-partition per pair), and reports aprogressrbar when available. - Bundled, documented example data:
gut_counts,gut_tree,gut_traits. -
referenceargument onhilldiv()—reference = c("pool", "sample")selects the reference tree depth for phylogenetic Hill numbers."pool"(default) reads every sample at one common depthT = mean(T_j)so values are mutually comparable (hilldiv2’smultibehaviour);"sample"reads each sample at its own depthT_j. The two coincide on ultrametric trees. The option is deliberately absent fromhillpart(), whereTis fixed at the Chiu et al. (2014) mean per-sample depth — the unique value for whichgamma / alphais a valid decomposition withbetain[1, N].
Bug fixes
-
Phylogenetic
hilldiv()alpha corrected. The per-sample phylogenetic Hill number previously raised branch lengthL_ito the powerqalong with abundance ((L_i a_i / T)^q), which matched no standard quantity and disagreed with the partition engine. Branch length is now a linear weight ((L_i / T) a_i^q, Chao et al. 2010), soq = 0recovers Faith’s PD / T and the per-sample value matcheshillpart()alpha at a single sample. This changes phylogenetichilldiv()andhillprof()outputs relative to earlier 3.0.0 development snapshots.
Infrastructure
- Added test-coverage (Codecov) and lint (lintr) GitHub Actions workflows.
- Added golden-value tests cross-checking the engine against
veganand hand-computed constants, plus edge cases (single taxon, empty sample, q = 1).
Compatibility
- The
hilldiv(),hillpart(),hilldiss(),hillsim(),hillpair(),hillred(),tss()andtraits2dist()names from hilldiv2 are preserved. The default return shape is now a tidydata.frame; useout = "matrix"for the hilldiv2-style matrix.