canonicalize_cell {CellaRepertorium} | R Documentation

## Find a canonical contig to represent a cell

### Description

Using filtering in `contig_filter_args` and sorting in `tie_break_keys` and `order` find a single, canonical contig to represent each cell Fields in `contig_fields` will be copied over to the `cell_tbl`.

### Usage

    canonicalize_cell(
      ccdb,
      contig_filter_args = TRUE,
      tie_break_keys = c("umis", "reads"),
      contig_fields = tie_break_keys,
      order = 1,
      overwrite = TRUE
    )

### Arguments

`ccdb` | `ContigCellDB()`
`contig_filter_args` | an expression passed to `dplyr::filter()`. Unlike `filter`, multiple criteria must be `&` together, rather than using commas to separate. These act on `ccdb$contig_tbl`
`tie_break_keys` | (optional) `character` naming fields in `contig_tbl` that are used sort the contig table in descending order. Used to break ties if `contig_filter_args` does not return a unique contig for each cluster
`contig_fields` | Optional fields from `contig_tbl` that will be copied into the `cluster_tbl` from the canonical contig.
`order` | The rank order of the contig, based on `tie_break_keys` to return. If `tie_break_keys` included an ordered factor (such as chain) this could be used to return the second chain.
`overwrite` | `logical` – should non-key fields in y be overwritten using x, or should a suffix (".y") be added

### Value

`ContigCellDB()` with some number of clusters/contigs/cells but with "canonical" values copied into `cell_tbl`

### See Also

`canonicalize_cluster()`

### Examples

    # Report beta chain with highest umi-count, breaking ties with reads
    data(ccdb_ex)
    beta = canonicalize_cell(ccdb_ex, chain == 'TRB',
    tie_break_keys = c('umis', 'reads'),
    contig_fields = c('umis', 'reads', 'chain', 'v_gene', 'd_gene', 'j_gene'))
    head(beta$cell_tbl)

    # Stable: only adds fields to `cell_tbl`
    stopifnot(dplyr::all_equal(beta$cell_tbl[ccdb_ex$cell_pk],
    ccdb_ex$cell_tbl[ccdb_ex$cell_pk], ignore_row_order = TRUE))

    #Report cdr3 with highest UMI count, but only when > 5 UMIs support it
    umi5 = canonicalize_cell(ccdb_ex, umis > 5,
    tie_break_keys = c('umis', 'reads'), contig_fields = c('umis', 'cdr3'))
    stopifnot(all(umi5$cell_tbl$umis > 5, na.rm = TRUE))

[Package CellaRepertorium version 1.0.0 Index]