R: Convert to a ra_ref object

as.ra_ref {cellranger} | R Documentation

## Convert to a ra_ref object

### Description

Convert various representations of a cell reference into an object of class `ra_ref`.

- `as.ra_ref` is NOT vectorized and therefore requires the input to represent exactly one cell, i.e. be of length 1.

- `as.ra_ref_v` accepts input of length >= 1 and returns a list of `ra_ref` objects.

### Usage

    as.ra_ref(x, ...)

    as.ra_ref_v(x, ...)

    ## S3 method for class 'character'
    as.ra_ref(x, fo = NULL, strict = TRUE, ...)

    ## S3 method for class 'character'
    as.ra_ref_v(x, fo = NULL, strict = TRUE, ...)

    ## S3 method for class 'cell_addr'
    as.ra_ref(x, ...)

    ## S3 method for class 'cell_addr'
    as.ra_ref_v(x, ...)

### Arguments

`x` | one or more cell references, as a character vector or `cell_addr` object
`...` | further arguments passed to or from other methods
`fo` | either `"R1C1"` (the default) or `"A1"` specifying the cell reference format; in many contexts, it can be inferred and is optional
`strict` | logical, affects reading and writing of A1 formatted cell references. When `strict = TRUE`, references must be declared absolute through the use of dollar signs, e.g., `$A$1`, for parsing. When making a string, `strict = TRUE` requests dollar signs for absolute reference. When `strict = FALSE`, pure relative reference strings will be interpreted as absolute, i.e. `A1` and `$A$1` are treated the same. When making a string, `strict = FALSE` will cause dollars signs to be omitted in the reference string.

### Value

a `ra_ref` object, in the case of `as.ra_ref`, or a list of them, in the case of `as.ra_ref_v`

### Examples

    ## as.ra_ref.character()
    as.ra_ref("$F$2")
    as.ra_ref("R[-4]C3")
    as.ra_ref("B4")
    as.ra_ref("B4", strict = FALSE)
    as.ra_ref("B$4")

    ## this is actually ambiguous! is format A1 or R1C1 format?
    as.ra_ref("RC2")
    ## format could be specified in this case
    as.ra_ref("RC2", fo = "R1C1")
    as.ra_ref("RC2", fo = "A1", strict = FALSE)

    ## as.ra_ref_v.character()
    cs <- c("$A$1", "Sheet1!$F$14", "Sheet2!B$4", "D9")
    ## Not run:
    ## won't work because as.ra_ref requires length one input
    as.ra_ref(cs)

    ## End(Not run)
    ## use as.ra_ref_v instead
    as.ra_ref_v(cs, strict = FALSE)
    ## as.ra_ref.cell_addr
    ca <- cell_addr(2, 5)
    as.ra_ref(ca)
    ## as.ra_ref_v.cell_addr()

    ca <- cell_addr(1:3, 1)
    ## Not run:
    ## won't work because as.ra_ref methods not natively vectorized
    as.ra_ref(ca)

    ## End(Not run)
    ## use as.ra_ref_v instead
    as.ra_ref_v(ca)

[Package cellranger version 1.1.0 Index]