NEWS.md

jfa 0.7.3

New features

• @federicapicogna added fairness_selection() to aid in the decision between fairness metrics. The function has an accompanying print() and plot() method.
• @lottemensink added plot(x, type = "sequential") to the evaluation() function when used with prior, materiality and data. The plot shows Bayes factors as a function of the sample size.

Bug fixes

• Fixed a bug in the evaluation() function using method = "hypergeometric" where the user could provide broken taints. These taints are now rounded to the nearest integer value.

jfa 0.7.2

Minor changes

• In the auditPrior() function, method = "factor" has been replaced with method = "power" to be consistent with existing terminology.
• selection() now always performs sampling with replacement when using items = "values" and method = "random" (Thanks to @lottemensink for the suggestion). This should not lead to substantial differences in typical audit populations.

jfa 0.7.1

New features

• Added the option to calculate a frequentist multi-stage sampling plan with the planning() function. This can be done by providing a vector of integers to the expected argument that specifies the intended sampling plan. For instance, expected = c(1, 0) gives the sample size for a two-stage sampling plan in which the auditor is allowed to extend the initial sample after finding one misstatement and is allowed to approve the population if the initial sample contains no misstatements.
• Added inflated methods to evaluate taintings in the evaluation function via method = "inflated.poisson" and method = "hurdle.beta". Since these methods rely on mcmc sampling, they can take any form of prior. They can also be fitted using maximum likelihood estimation with prior = FALSE.

Minor changes

• For all plotting functions, type = "estimates" is now the default option.

Major changes

• Removed the report() function as it did not align with the rest of the functionality in the package.

Bug fixes

• Fixed a bug in selection() where the numeric data in the sample was returned as character if the original data was entered as character only (i.e., selection(data.frame(x = c("hello", "bye", "hi")), size = 2)).
• N.units is now only taken from the prior if the user does not provide it manually to the planning() and evaluation() functions.

jfa 0.7.0

New features

• Added a new function model_fairness() to compute fairness metrics for algorithm auditing on the basis of predictions of an algorithm.

Minor changes

• In the evaluation() function, the typical stringer bound has been changed from method = "stringer" to method = "stringer.binomial". Furthermore, additional methods stringer.poisson and stringer.hypergeometric are added that apply the stringer bound using the Poisson and hypergeometric distributions, respectively. The stringer method will remain for now but redirect to stringer.binomial.
• Compatibility with rstantools 2.3.1.

jfa 0.6.7

New features

• digit_test() function now returns element estimates containing observed proportions and their corresponding confidence intervals. The plot output also shows these intervals around the estimates.

jfa 0.6.6

Bug fixes

• Changed the links to the images in the vignettes from absolute links to GitHub to relative links as to avoid problems with GitHub servers being unavailable in the future.

jfa 0.6.5

New features

• Additional possibilities to create, plan and evaluate using nonparametric prior distributions.
• Added functionality for stratified evaluation in the evaluation() function.
• Integrated the auditing functionality of the digitTests package via the digit_test() and repeated_test() functions.

Bug fixes

• Fixed a bug where the proportion of value in summary(selection) was displayed incorrectly.

Minor changes

• Improved the error handling and error messages.

jfa 0.6.4

Minor changes

• Resolved CRAN note Warning: <img> attribute "align" not allowed for HTML5.
• Improve compatibility with R 4.2.0.

jfa 0.6.3

Minor changes

• The value for x in evaluation() and expected in planning() is now automatically ceiled (while throwing a warning) for method = "hypergeometric".
• Improved overall documentation.

jfa 0.6.2

Major changes

• Removed the output and functions related to the class jfaPredictive. The probabilities for the prior and posterior predictive distributions can be obtained by calling the predict() function.

Minor changes

• The value for N.units in auditPrior(), planning(), and evaluation() is now automatically ceiled for likelihood/method = 'hypergeometric'.
• Implemented a warning message when the likelihood in the prior does not match with the likelihood/method inputs for planning() and evaluation(). The likelihood from the prior is leading in these cases and will overrule the other options.

jfa 0.6.1

New features

• Added argument randomize to the selection() function, which allows the user to randomly shuffle the items in the population before selection. Note that specifying randomize = TRUE overrules order.

Bug fixes

• Fixed a bug where the maximum sample size was not reached (i.e., planning stopped at max - 1).

Major changes

• The order argument in selection() no longer accepts a logical, but instead takes the column name of the ranking variable in the data.

Minor changes

• Adjusted an error in the text of the selection vignette.
• Rewritten most of the vignettes.

jfa 0.6.0

New features

• Added argument alternative with possible options less (default), two.sided, and greater to the evaluation() function that allows control over the type of hypothesis test to perform and the type of confidence / credible interval to calculate.
• Added predict.jfaPrior() and predict.jfaPosterior() that produce predictions for the data under the prior or posterior distribution.
• Added method = 'param' to function auditPrior() which takes as input the raw alpha and beta parameters of the prior distribution.
• Added method = 'strict' to function auditPrior() which constructs an (improper) prior distribution that yields the same results (with respect to sample sizes and upper limits) as classical procedures.
• Added the modified seed sampling algorithm (method = 'sieve') to selection().
• Added a new vignette that describes the sampling methodology implemented in jfa.
• objects from auditPrior(), planning(), and evaluation() now contain information about the posterior predictive distribution when N.units is specified.

Major changes

• From jfa 0.5.7 to jfa 0.6.0 there has been a major overhaul in the names of function arguments. This is done so that the calls integrate better with general R syntax and the package gets more user-friendly. I apologize for any inconvenience this may cause. The following names have been changed:
  • median -> impartial (in auditPrior())
  • sampleK -> x (in auditPrior())
  • sampleN -> n (in auditPrior())
  • N -> N.units (in auditPrior())
  • maxSize -> max (in planning())
  • increase -> by (in planning())
  • withReplacement-> replace (in selection())
  • ordered -> order (in selection())
  • ascending -> decreasing (in selection())
  • intervalStartingPoint -> start (in selection())
  • algorithm -> method (in selection())
  • expectedErrors -> expected (in auditPrior() and planning())
  • confidence -> conf.level (in auditPrior(), planning(), and evaluation())
  • pHmin -> p.hmin (in auditPrior())
  • minPrecision -> min.precision (in auditPrior(), planning(), and evaluation())
  • population -> data (in selection())
  • kSumstats -> x (in evaluation())
  • nSumstats -> n (in evaluation())
  • sample -> data (in evaluation())
  • bookValues -> values (in selection() and evaluation())
  • auditValues -> values.audit (in evaluation())
  • counts -> times (in evaluation())
  • popBookValues -> N.units (in evaluation())
  • rohrbachDelta -> r.delta (in evaluation())
  • momentPopType -> m.type (in evaluation())
  • csA -> cs.a (in evaluation())
  • csB -> cs.b (in evaluation())
  • csMu -> cs.mu (in evaluation())
  • records -> items (in selection())
  • mus -> values (in selection())
  • hypotheses -> hyp (in auditPrior())
• poisson is now the default likelihood / method for all functions since it is the most conservative.
• method = 'interval' is now the default selection method.
• The default prior distributions used when method = 'default' or prior = TRUE are now set to the gamma(1, 1), beta(1,1), and beta-binomial(1, 1) priors.
• The times (former counts) argument in evaluation() must now be indicated as a column name in the data instead of a vector.
• nPrior and kPrior have been removed from the planning() and evaluation() functions. All prior distributions must now be specified using prior = TRUE (noninformative priors) or using a call to auditPrior().
• Removed the auditBF() function since its value is available through evaluation(materiality = x, prior = auditPrior(method = 'impartial', materiality = x))

Minor changes

• It is now allowed for x and n to have the same value in evaluation().
• The parameters for an impartial beta-binomial prior are now calculated more efficiently in the case of zero expected errors.

jfa 0.5.7

Minor changes

• The logo is now displayed in the ?jfa-package help file.
• The cheat sheet link has changed in the README file.

jfa 0.5.6

Bug fixes

• Fixed a bug in the print.jfaEvaluation() call if there was no performance materiality specified and prior = TRUE.

jfa 0.5.5

New features

• The print() functions now return a more concise description of the relevant output.
• Added summary() functions for all returned objects that take over the former (elaborate) output of the print() functions.
• Implemented a new function auditBF() which computes Bayes factors from summary statistics of an audit sample.

Bug fixes

• Fixed a bug in evaluation() in which the likelihood stored in the prior was not properly passed to the function.
• Fixed an error in the calculation of the posterior mode of the beta distribution.

Minor changes

• Restored the default value (0.95) for the 'confidence' argument in all applicable functions.

jfa 0.5.4

New features

• Objects with class jfaPosterior as returned by evaluation()$posterior and planning()$expectedPosterior can now be used as input for the prior argument in the planning() and evaluation() functions.

Bug fixes

• Fixed a bug in method = 'bram' in the auditPrior() function where the prior parameters would go off to infinity when expectedError = 0.

Major changes

• Now calculates the upper bound for the population errors according to the hypergeometric distribution via an inverted hypothesis test. As a result of this method, the planning() function does not require a value for the materiality anymore when planning with the hypergeometric likelihood.

Minor changes

• Added a benchmark for the MUS package to the unit tests.
• Improved plots with better titles and axes labels.

jfa 0.5.3

New features

• Made expectedErrors > 0 available for method = 'hypotheses' in the auditPrior() function.
• Made method = 'hypotheses' and method = 'impartial' in the auditPrior() function available for likelihood = 'hypergeometric'.
• Added bram as a method for the auditPrior() function. method = 'bram' computes a prior distribution with a given mode (expectedError) and upper bound (ub).

Bug fixes

• Fixed an error in the mode of the gamma posterior distribution from the evaluation() function in which +1 was added to the beta parameter, resulting in slightly lower modes than the correct ones.
• Made a correction to the calculation of the beta-binomial prior and posterior so that the posterior parameter N has the correct value of N = N - n (current) instead of N - n + k (before).

Major changes

• Removed the default value confidence = 0.95 in all applicable functions. confidence currently has no default value so that the user is required to give an input.
• Changed the default likelihood = 'poisson' in the planning() function to likelihood = 'binomial' to be consistent across all functions.
• Changed the order of most function arguments so that materiality and minPrecision are among the first ones to be shown.

Minor changes

• Updated the documentation for all functions with more simple examples.

jfa 0.5.2

New features

• Update the poisson evaluation calculation so that it allows for fractional errors.

Bug fixes

• Fixed an error in the hypergeometric upper bound calculation that was accidentally based on the phyper() function instead of the qhyper() function, which resulted in lower bounds than usual.

Minor changes

• Add statistical tables with output (sample sizes, upper limits, Bayes factors) to the GitHub repository in pdf format.
• Changed the computation method of the sample sizes for hypergeometric and beta-binomial distributions so that they are faster.

jfa 0.5.1

Bug fixes

• Reduced the size of the tarball by adding files to the .Rbuildignore
• Fixed a bug in selection() where if population is sorted or modified, bv still retained the old ordering and data. The resulting sample was overweighted towards small values and/or still contained negative values (Thanks to @alvanson).

jfa 0.5.0

New features

• Add a function report() that automatically generates an audit report.

Major changes

• Removed the sampling() function, which is now replaced entirely with the selection() function.
• Changed the output of the evaluation() function when an estimator is used.

jfa 0.4.0

New features

• Added digits argument in the internal jfa:::print.jfaPrior(), jfa:::print.jfaPlanning(), jfa:::print.jfaSelection(), and jfa:::print.jfaEvaluation() functions to control rounding in printing.
• Added description, statistics, specifics and hypotheses to the output of the auditPrior() function.
• Added class jfaPosterior with print() and plot() methods.
• Added expectedPosterior of class jfaPosterior to the output of the planning() function, includes description, statistics and hypotheses.
• Added posterior of class jfaPosterior to the output of the evaluation() function, includes description, statistics and hypotheses.

Bug fixes

• Implemented improved calculation of prior parameters in the auditPrior() function for method = impartial when expectedErrors > 0.

Major changes

• Add a warning message to the sampling() function that it will be deprecated from 0.5.0 onward. You can use selection() instead, since sampling() causes namespace issues with other packages.

Minor changes

• Changed the class jfaSampling to jfaSelection. This should not have any consequences.

jfa 0.3.1

Bug fixes

• Fixed a bug in the planning() function that did not allow the user to plan for a monetary sample when their population size was too low.
• Fixed a bug in the planning() function that did not allow the user to select a non-integer number of expected errors when there was a prior involved.

Minor changes

• Added unit tests that regularly verify results of the planning() and evaluation() functions against benchmarks.

jfa 0.3.0

New features

• Implemented the argument counts in the evaluation() function that quantifies how many times each observation should be evaluated due to being selected multiple times in the selection stage.

jfa 0.2.0

New features

• Implemented prior construction methods default, impartial, hypotheses, sample, and factor in the auditPrior() function. In addition to the already supported arm method, these methods allow the auditor to incorporate more sources of audit information into the prior distribution.
• Implemented minPrecision argument in the planning() function that allows auditors to calculate a sample size so that the difference between the posterior upper confidence bound and the most likely error is lower than the set minimum precision. Also implemented in the evaluation() function as a requirement to approve the population.
• Return the value mle from the evaluation() function, which quantifies the most likely error. Also return the value of the precision from this function.
• Implemented increase argument in the planning() function that allows the user to increase the sample size with a set amount each step of the iterations.

Minor changes

• Implemented more efficient versions of the monetary unit sampling algorithms.
• Changed the x-axis labels in the default plot to theta instead of misstatement.

jfa 0.1.0

New features

• First version of the jfa package. The package provides four functions: auditPrior(), planning(), sampling(), and evaluation().