Clean up lifting docs

- closes SomaLogic#82

R/lift-adat.R

@@ -3,38 +3,61 @@
 #' The SomaScan platform continually improves its technical processes
 #' between assay versions; from changing reagents, liquid handling equipment,
 #' and increased analyte content. However, these upgrades can result in
-#' minute differences in RFU space for a given analyte, requiring a calibration
+#' minute measurement differences for a given analyte, requiring a calibration
 #' (aka "lifting" or "bridging") to bring RFUs into a comparable space.
-#' This is accomplished by applying an analyte-specific scalar to each analyte
-#' RFU (ADAT column). The scalar values themselves are typically provided
-#' via `*.xlsx` file, which can be parsed via [read_annotations()]. See Details.
+#' This is accomplished by applying an analyte-specific scalar
+#' (i.e. a linear transformation) to each analyte RFU (ADAT column).
+#' The scalar values themselves are provided in a SomaScan annotations file
+#' (`*.xlsx`), which can be parsed via [read_annotations()].
 #'
-#' Lifting between various versions requires a specific
-#' annotations file containing scalars specific to desired lifting direction.
-#' For example, to "lift" between `v4.1` -> `v4.0`, you *must* be working
-#' with SomaScan data in `v4.1` space and an annotations file containing
-#' scalars to convert __to__ `v4.0`.
-#' Likewise, "lifting" from `v4.0` -> `v4.1` requires
-#' a separate annotations file and a `soma_adat` from SomaScan `v4.0`.
+#' Lifting between SomaScan versions no longer requires an
+#' annotations file containing scalars. We now enable users to pass
+#' a `bridge =` parameter, indicating the direction of the bridge.
+#' For example, to "lift" between `11k` -> `7k`, you _must_ be acting on
+#' SomaScan data in `11k` RFU space and would pass `bridge = "11k_to_7k"`.
+#' Likewise, "lifting" from `7k` -> `5k` requires `bridge = "7k_to_5k"`.
+#' Additionally, you may also lift directly from `11k` -> `5k`
+#' (aka "double-bridge") with `bridge = "11k_to_5k"`.
+#' See below for all options for the `bridge =` argument.
+#'
+#' Table of SomaScan Assay versions:
+#' \tabular{lll}{
+#'   **Version**  \tab **Commercial Name** \tab **Size** \cr
+#'   `V4`         \tab 5k                  \tab 5284     \cr
+#'   `v4.1`       \tab 7k                  \tab 7596     \cr
+#'   `v5.0`       \tab 11k                 \tab 11083    \cr
+#' }
+#'
+#' @section Extra Columns:
+#' Newer versions of SomaScan typically have additional content, i.e.
+#' new reagents added to the multi-plex assay that bind to new proteins.
+#' Reagents that are _not_ in the "earlier" version (i.e. new reagents)
+#' are maintained their value unmodified in the returned object.
+#' Users may need to drop these columns in order to combine data with
+#' that of a study originating with the previous SomaScan version, e.g. with
+#' [collapseAdats()].
 #'
 #' @inheritParams params
 #' @param bridge The direction of the lift (i.e. bridge).
 #' @param anno.tbl Deprecated.
-#' @return A "lifted" `soma_adat` object corresponding to the scaling
-#'   reference in the `anno.tbl`. RFU values are rounded to 1 decimal to
-#'   match standard SomaScan delivery format.
+#' @return [lift_adat()]: A "lifted" `soma_adat` object corresponding to
+#'   the scaling requested in the `bridge` param. RFU values are
+#'   rounded to 1 decimal place to match standard SomaScan delivery format.
 #' @examples
-#' # `example_data` is SomaScan V4 (5k)
+#' # `example_data` is SomaScan (V4, 5k)
 #' adat <- head(example_data, 3L)
-#' getSomaScanVersion(example_data)
+#' getSomaScanVersion(adat)
 #'
-#' # perform the 'lifting'
-#' lift_7k <- lift_adat(adat, "5k_to_7k")
-#' is_lifted(lift_7k)
+#' getSignalSpace(adat)
+#'
+#' # perform 'lift'
+#' lift_11k <- lift_adat(adat, "5k_to_11k")
+#' is_lifted(lift_11k)
 #'
 #' # attributes updated to reflect the 'lift'
-#' attr(lift_7k, "Header")$HEADER$SignalSpace
-#' attr(lift_7k, "Header")$HEADER$ProcessSteps
+#' attr(lift_11k, "Header")$HEADER$SignalSpace
+#' attr(lift_11k, "Header")$HEADER$ProcessSteps
+#'
 #' @importFrom tibble enframe deframe
 #' @importFrom lifecycle deprecated is_present deprecate_warn
 #' @export
@@ -100,7 +123,7 @@ lift_adat <- function(adat,
 #' in the `soma_adat` attributes.
 #'
 #' @rdname lift_adat
-#' @return Logical. Whether `adat` has been lifted.
+#' @return [is_lifted()]: Logical. Whether `adat` has been lifted.
 #' @export
 is_lifted <- function(adat) {
   x <- attr(adat, "Header.Meta")$HEADER