propagate_uncertainty
Read-only
Uncertainty through any qPCR quantity, three independent ways at once. Give it the expression you actually report - a ratio, a normalised expression, an efficiency-corrected quantity - and a mean and standard deviation for each variable in it (or the replicate observations themselves), and it returns the analytic Taylor propagation, a Monte-Carlo simulation and a permutation resampling side by side, because they disagree in informative ways: the Taylor arm is exact only for a linear expression, and a ratio is not linear.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nsim | No | Monte-Carlo draws. Only applies when do_sim is true. | |
| seed | No | R's `set.seed` value, so a simulated or permuted run is reproducible and citable. Advanced. | |
| ties | No | `raw` only: which columns are resampled together, as one whole number per column — `1,1,2` permutes the first two as a block. Blank permutes every column on its own. Use it when two columns are readings of the same tube. Only applies when do_perm is true. | |
| input | No | what `variables` holds. `stat` = a summary per variable; `raw` = the replicate observations. `raw` is the stronger input: it carries the measured covariance between variables and it is the only one the permutation arm can resample, because permutation resamples observed ROWS and a mean with an SD beside it has none. | stat |
| nperm | No | permutations. Only applies when do_perm is true. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| do_sim | No | run the Monte-Carlo arm — draw from the joint normal and push every draw through the expression. Correct for any nonlinearity, at the cost of being a sample. | |
| do_perm | No | `raw` only: run the permutation arm, which resamples the observed rows and so assumes no distribution at all. It also returns p-values for the three hypotheses upstream tests. Only applies when input is raw. | |
| use_cov | No | `raw` only: propagate the measured covariance between the variables, not just their variances. Two Ct values read off the same plate are not independent, and treating them as independent understates the error of their ratio. Only applies when input is raw. | |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| dist_sim | No | the distribution drawn from: `norm`, or `tnorm` truncated at zero — the one to use when a variable is a concentration or a fluorescence and a negative draw is not a possible measurement. Only applies when do_sim is true. | norm |
| variables | Yes | the numbers. In `stat` mode: a header row `variable, mean, sd` and one row per variable. In `raw` mode: a header row of variable names and one row per replicate, blank cells left blank (they are dropped pairwise, never read as zero). Tab- or comma-separated. | |
| conf_level | No | the level the reported bounds are read at. | |
| expression | Yes | the quantity whose uncertainty is wanted, in R's syntax over the variable names below: `x/y`, `2^-(a - b)`, `(Etar^-Cttar)/(Eref^-Ctref)`. Every name in it must appear in `variables`. | |
| second_order | No | include the second-order Taylor terms. On is upstream's default and is what makes the analytic arm usable on a ratio; off gives the classic first-order propagation of error. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gradient | Yes | the printed partial derivative per variable, and its value at the means | |
| permuted | Yes | the permutation arm, same fields. Null in `stat` mode, which has no rows to resample | |
| confLower | Yes | lower analytic bound at `conf_level` | |
| confUpper | Yes | upper analytic bound | |
| simulated | Yes | the Monte-Carlo arm: mean, sd, median, mad and its own interval. Every field null when it was not run — a nonlinear expression whose two arms disagree is the finding, not a display detail | |
| variables | Yes | the variable names the run used, in expression order — every other array here is in this order | |
| permPValues | Yes | permutation p-values for the three hypotheses upstream tests, in `perm > init` / `perm == init` / `perm < init` order | |
| propagatedSd | Yes | the analytic (Taylor) standard error — the number to report when the expression is close to linear | |
| contributions | Yes | how much of the propagated variance each variable contributes, in %, first-order — which measurement to make more precisely | |
| firstOrderMean | Yes | the expression evaluated at the input means, before the second-order correction | |
| propagatedMean | Yes | the expression evaluated at the input means, with the second-order correction when it is on | |
| secondOrderMean | Yes | the mean with the second-order Taylor correction applied, whether or not the reported mean uses it |