updateGamma: Update Gamma (percentile value).
In QuantileGradeR: Quantile-Adjusted Restaurant Grading

Description Usage Arguments Details Value

updateGamma is the percentile update function called by percentileSeek as percentileSeek attempts to match a set of grade proportions to a set of desired.props.

1
2
3

updateGamma(scores, z, desired.props, gamma.perc, index.to.update,
  restaurant.tol = 10, iter = 1, max.iterations = 20, gamma_upper = NA,
  gamma_lower = NA, resolve.ties = FALSE)

`scores`	Numeric vector of size `n`, where `n` is the number is restaurants to be graded. `scores[i]` represents the mean or raw inspection score for restaurant `i`.
`z`	Character vector representing ZIP codes. `z[i]` is the ZIP code for restaurant `i`.
`desired.props`	Numeric vector representing desired global grade proportions across the entire jurisdiction. `desired.props[j]` is the desired proportion of total (gradeable) restaurants in the `j`th highest grading category.
`gamma.perc`	Numeric vector representing an initial set of percentiles.
`index.to.update`	Integer value in the set `1:(length(desired.props)-1)` that represents the particular percentile to be updated in the current run of `updateGamma`. (Percentiles are not updated simultaneously, but rather are updated sequentially with the smallest percentiles being the first to be updated.)
`restaurant.tol`	Integer value representing the maximum difference in number of restaurants suggested by `desired.props` and the actual number of restaurants in each of the top `(length(desired.props) - 1)` grade categories.
`iter`	Integer value representing the current iteration of `updateGamma`.
`max.iterations`	Integer value specifying the maximum number of calls of the `updateGamma` percentile update function for each of the sought after percentiles.
`gamma_upper`	Numeric or NA value representing a value of `gamma.perc[index.to.update]` that results in too many restaurants gaining the desired grade proportion.
`gamma_lower`	Numeric or NA value representing a value of `gamma.perc[index.to.update]` that results in too few restaurants gaining the desired grade proportion.
`resolve.ties`	Boolean value specifying interpretation of how the function's returned percentile will be applied across the subunits see: percentileSeek. Should as close to (desired.props[1])% of restaurants in a ZIP code receive an "A" grade, and as close to (desired.props[2])% of restaurants in a ZIP code receive "B" grades (`resolve.ties = TRUE` case)? Or should the returned percentiles be interpretted as R quantile `Type = 1` percentiles, and at least (desired.props[1])% of restaurants in a ZIP code receive an "A" grade?

updateGamma performs the update of gamma.perc[index.to.update]. In particular, gamma.perc[index.to.update] will be updated until either the number of updates has reached max.iterations, or the difference between the proportion of (gradeable) restaurants scoring the (index.to.update)th highest grade is within (restaurant.tol/ no.gradeable.rests) of the desired proportion, where no.gradeable.rests is the number of gradeable restaurants (restaurants that have both ZIP code and inspection score information). Initially, gamma.perc[index.to.update] is updated according to the rule gamma.perc[index.to.update] <- (gamma.perc[index.to.update] - diff.aj.desired), where diff.aj.desired is the difference between the actual proportion of restaurants assigned the grade of interest and the desired proportion. However, if the algorithm locates values of gamma.perc[index.to.update] that produce grade proportions that are both higher and lower than the desired proportion, gamma_upper and gamma_lower respectively, the update rule becomes gamma.perc[index.to.update]<- 0.5*(gamma_upper + gamma_lower), as in the bisection root finding method.