Skip to contents

BPCells fragments can be interconverted with GRanges and data.frame R objects. The main conversion method is R's builtin as() function, though the convert_to_fragments() helper is also available. For all R objects except GRanges, BPCells assumes a 0-based, end-exclusive coordinate system. (See genomic-ranges-like reference for details)

Usage

# Convert from R to BPCells
convert_to_fragments(x, zero_based_coords = !is(x, "GRanges"))
as(x, "IterableFragments")

# Convert from BPCells to R
as.data.frame(bpcells_fragments)
as(bpcells_fragments, "data.frame")
as(bpcells_fragments, "GRanges")

Arguments

x

Fragment coordinates given as GRanges, data.frame, or list. See help("genomic-ranges-like") for details on format and coordinate systems. Required attributes:

  • chr, start, end: genomic position

  • cell_id: cell barcodes or unique identifiers as string or factor

zero_based_coords

Whether to convert the ranges from a 1-based end-inclusive coordinate system to a 0-based end-exclusive coordinate system. Defaults to true for GRanges and false for other formats (see this archived UCSC blogpost)

Value

convert_to_fragments(): IterableFragments object

Examples

frags_table <- tibble::tibble(
  chr = paste0("chr", 1:10),
  start = 0,
  end = 5,
  cell_id = "cell1"
)
frags_table
#> # A tibble: 10 × 4
#>    chr   start   end cell_id
#>    <chr> <dbl> <dbl> <chr>  
#>  1 chr1      0     5 cell1  
#>  2 chr2      0     5 cell1  
#>  3 chr3      0     5 cell1  
#>  4 chr4      0     5 cell1  
#>  5 chr5      0     5 cell1  
#>  6 chr6      0     5 cell1  
#>  7 chr7      0     5 cell1  
#>  8 chr8      0     5 cell1  
#>  9 chr9      0     5 cell1  
#> 10 chr10     0     5 cell1  

frags_granges <- GenomicRanges::makeGRangesFromDataFrame(
 frags_table, keep.extra.columns = TRUE
)
frags_granges
#> GRanges object with 10 ranges and 1 metadata column:
#>        seqnames    ranges strand |     cell_id
#>           <Rle> <IRanges>  <Rle> | <character>
#>    [1]     chr1       0-5      * |       cell1
#>    [2]     chr2       0-5      * |       cell1
#>    [3]     chr3       0-5      * |       cell1
#>    [4]     chr4       0-5      * |       cell1
#>    [5]     chr5       0-5      * |       cell1
#>    [6]     chr6       0-5      * |       cell1
#>    [7]     chr7       0-5      * |       cell1
#>    [8]     chr8       0-5      * |       cell1
#>    [9]     chr9       0-5      * |       cell1
#>   [10]    chr10       0-5      * |       cell1
#>   -------
#>   seqinfo: 10 sequences from an unspecified genome; no seqlengths

#######################################################################
## convert_to_fragments() example
#######################################################################
frags <- convert_to_fragments(frags_granges)
frags
#> IterableFragments object of class "UnpackedMemFragments"
#> 
#> Cells: 1 cells with names cell1
#> Chromosomes: 10 chromosomes with names chr1, chr2 ... chr10
#> 
#> Queued Operations:
#> 1. Read uncompressed fragments from memory


#######################################################################
## as(x, "IterableFragments") example
#######################################################################
frags <- as(frags_table, "IterableFragments")
frags
#> IterableFragments object of class "UnpackedMemFragments"
#> 
#> Cells: 1 cells with names cell1
#> Chromosomes: 10 chromosomes with names chr1, chr10 ... chr9
#> 
#> Queued Operations:
#> 1. Read uncompressed fragments from memory


#######################################################################
## as(bpcells_fragments, "data.frame") example
#######################################################################
frags_table <- as(frags, "data.frame")
frags_table
#>      chr start end cell_id
#> 1   chr1     0   5   cell1
#> 2  chr10     0   5   cell1
#> 3   chr2     0   5   cell1
#> 4   chr3     0   5   cell1
#> 5   chr4     0   5   cell1
#> 6   chr5     0   5   cell1
#> 7   chr6     0   5   cell1
#> 8   chr7     0   5   cell1
#> 9   chr8     0   5   cell1
#> 10  chr9     0   5   cell1


#######################################################################
## as(bpcells_fragments, "GRanges") example
#######################################################################
frags_granges <- as(frags, "GRanges")
frags_granges
#> GRanges object with 10 ranges and 1 metadata column:
#>        seqnames    ranges strand |  cell_id
#>           <Rle> <IRanges>  <Rle> | <factor>
#>    [1]     chr1       1-5      * |    cell1
#>    [2]    chr10       1-5      * |    cell1
#>    [3]     chr2       1-5      * |    cell1
#>    [4]     chr3       1-5      * |    cell1
#>    [5]     chr4       1-5      * |    cell1
#>    [6]     chr5       1-5      * |    cell1
#>    [7]     chr6       1-5      * |    cell1
#>    [8]     chr7       1-5      * |    cell1
#>    [9]     chr8       1-5      * |    cell1
#>   [10]     chr9       1-5      * |    cell1
#>   -------
#>   seqinfo: 10 sequences from an unspecified genome; no seqlengths