NEWS.md
This release corrects statistical errors found in a review of the package. Some results change. Check the items under CHANGES IN RESULTS before comparing with analyses run on earlier versions.
kendallTau() on matrices tests the average tau with each row (participant) as an independent ranking, and weights rows by their number of pairs. Earlier versions pooled all pairs into one ranking of N_effective items, which understated precision. With 2,000 random triads the z-values had a standard deviation of about 0.2 instead of 1, so real associations were often reported as not significant. Expect larger z-values and smaller p-values in trials with many participants. Average tau is unchanged for complete triads. N_effective is still reported, for reference only.
kendallTau() gains alternative = c("two.sided", "greater", "less"). The default is now two-sided. Earlier versions reported a one-sided p-value for a positive association. The column name Pr(>|z|) is unchanged. null.rm is now passed from the matrix method to each row.
crossvalidation() reports Kendall’s tau for Plackett-Luce trees on the held-out test set. Earlier versions compared predictions with the training rankings, an in-sample measure. Values will be lower and honest.
preference_index() counts each item once per set. Earlier versions inflated n by the number of other items in each set and gave larger sets more weight in the averages. Sets with a single ranked item are skipped. The bottom probability is computed exactly by recursion over subsets.
regret() assigns each regret to the right item when nodes are not in sorted order (for example terminal node 10 before node 3). This affected trees with node ids of 10 or more, including worthSE and regretSE.
regret() weights nodes by their share of observations for pltree objects, and models by their number of rankings for lists of PlackettLuce models, so a small node no longer counts as much as a large one. Worst regret, a worst case, is not weighted. The new node.weights argument sets weights; equal weights reproduce the previous results.
anova() for Plackett-Luce models no longer rounds the log-likelihood difference before computing the statistic, and computes the p-value with lower.tail = FALSE.
likelihood_ratio() computes the p-value with lower.tail = FALSE.
kendallTau_bootstrap() resamples participants with replacement and returns the pair-weighted average tau of each resample. Earlier versions computed tau on only four subsets of the data and bootstrapped those four values, which gave a poor estimate of the variability of tau. The function also reset the random number stream; with seed it now leaves the caller’s stream unchanged, and without seed it uses the current stream. Arguments and output format are unchanged.
crossvalidation() keeps folds aligned with the data when rows are dropped for missing values, accepts folds given as a list of training rows, stops with an error when a model or a score cannot be computed (instead of returning zeros), and no longer changes the caller’s random number stream when seed is given. The package of the model (for example ‘PlackettLuce’ or ‘gnm’) must be attached, and the function says so when it is not.likelihood_ratio() checks the split vector, accepts grouped rankings as in its documented example and passes ... to PlackettLuce().rank_tricot2() reads factor ranks by their values and gains strict = FALSE, an opt-in check for missing, duplicated, tied and non-consecutive ranks.rank_tricot() warns when the same item appears twice in a row.Corrected typos and unclear wording in the help pages (for example btpermute() named a non-existent argument n.iteractions, and the arguments of the default method of kendallW() were described as pltree objects).
Unit tests in tests/testthat cover these functions and run under R CMD check, including a simulation of the null distribution of kendallTau().
Added an R CMD check workflow for Linux, macOS and Windows, and AGENTS.md, a guide for AI agents working on the package.
preference_index() to compute a model-based preference indexrank_tricot2() — a redesigned ranking parser for tricot data.rank_numeric() to interface with rank_tricot2() for improved performance and error handling.plot.pltree()
kendallTau_permute() and kendallTau_bootstrap()
plot.PlackettLuce()
cassava to the datasetscassava consumer testing data and new vignetteworth_map() are extracted using stats::coefficients() instead of psychotools::itempar()
resample() to re-sample Plackett-Luce coefficientsregret()pairwise_probs() to compare worth parameters following the Luce’s Axiomregret(). Using sum(x^2) instead of sum(x)^2
anova() method for PlackettLuce modelslikelihood_ratio()
kendallTau() returns Z-value and p-valuesrank_binomial() and rank_paircomp() are renamed as set_binomialfreq() and set_paircomp(), respectivelyvalidate.rankings to rank_tricot() to help in identifying possible issues in input tricot ranking like NA, ties or letters different than A, B or Caverage to kendallTau() to allow returning the kendall correlation for each entry in a matrix and PlackettLuce rankingna.omit to kendallTau() to remove entries with NA
= instead of <- to avoid typing stressplot.pltree() when multi-comparison is required but multicompView is not loaded.reliability(), btpermute(), pseudo_rank(), kendallW()
plot.pltree() to build branches and panels independentlyplot_tree()
rank_numeric() deals with ids of class charactersref can be used in multicompPL() to select the reference itemplot() method for summarise_agreement() using the argument scales, where scales = 100 is to set the scale from 0-100 and scales = 1 for a scale from 0-1multcompPL()
rank_binomial() in assigning the ids when argument disaggregate = TRUE
btpermute(), with the fix n.formula = n.vars + 1forward()
btpermute() is added for model selection with BTm()rainfall(), temperature(), ETo() and GDD() migrates to climatrends
rank_numeric() in restricted to floating point numbers. Integer values are ranked as provided by input.rainfall() and temperature() now allows for time series indicesRename functions agreement(), dominance(), favourite(), and victories() with the tag summarise and add it into summarise functions. No warking message provided. New functions are summarise_agreement(), summarise_dominance(), summarise_favourite(), and summarise_victories()
Argument ‘index’ is removed from rainfall() and temperature(), all indices are given by default
.get_timeseries() now implements the Euclidean method to search for its nearest neighbour in the nasapower output. This optmises the function and reduce dependenciespseudoR2() as a S3 method for objects of class “glm”, “gnm”, “bttree” and “pltree”kendallTau() as S3 method for objects of class “numeric”, “matrix”, “data.frame”, “rankings”, “grouped_rankings”predict() method for crossvalidation and rank_decimal() deprecatedrank_numeric() and rank_tricot() replaces rank_PL(). NO warning message addedpredict() method for crossvalidation objectspseudoR2() for object of class “pltree” extracts null loglik from PlackettLuceto_rankings() by rank_PL(). Warning message addednum2rank() by rank_decimal(). No warning message addedto_paircomp() by rank_paircomp(). No warning message added