Skip to contents

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 hierarchy now weights units linearly (Routledge/Tsallis-type), so every nested beta is at least one for q >= 0 and alpha * prod(beta) = gamma holds exactly in unbalanced designs. Earlier p_u^q weights 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 at q != 1 now differ from earlier development versions by a few per cent (and slightly at q = 1 for functional diversity).
  • hillpart() gains weights ("equal", "abundance" or a numeric vector) for hierarchical designs, a reference depth for phylogenetic hierarchies (ultrametric trees) and a grid of tau values for functional hierarchies (one hierarchy per tau).
  • hilldiss() and hillsim() 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() and hillcontrib(): S and V are now described as turnover measures and U and C as overlap complements, C is one minus Morisita-Horn at q = 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.md and CITATION.cff now 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 from hillpart(), hilldiss() and hillred() 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-facing hill* functions are thin wrappers around it.
  • Single validation/alignment layer (prep_data()) that checks names with setequal() 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, phyloseq and TreeSummarizedExperiment objects.
  • Fast ape-based post-order tree traversal replaces geiger::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() and hillred() now return long-format data.frames with print(), plot() and (when ggplot2 is installed) autoplot() methods. Pass out = "matrix" for the legacy shape.
  • Explicit type argument — 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 a progressr bar when available.
  • Bundled, documented example data: gut_counts, gut_tree, gut_traits.
  • reference argument on hilldiv() — reference = c("pool", "sample") selects the reference tree depth for phylogenetic Hill numbers. "pool" (default) reads every sample at one common depth T = mean(T_j) so values are mutually comparable (hilldiv2’s multi behaviour); "sample" reads each sample at its own depth T_j. The two coincide on ultrametric trees. The option is deliberately absent from hillpart(), where T is fixed at the Chiu et al. (2014) mean per-sample depth — the unique value for which gamma / alpha is a valid decomposition with beta in [1, N].

Bug fixes

  • Phylogenetic hilldiv() alpha corrected. The per-sample phylogenetic Hill number previously raised branch length L_i to the power q along 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), so q = 0 recovers Faith’s PD / T and the per-sample value matches hillpart() alpha at a single sample. This changes phylogenetic hilldiv() and hillprof() 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 vegan and hand-computed constants, plus edge cases (single taxon, empty sample, q = 1).

Compatibility