# Using Iterators in SeqVarTools

## Introduction

Iterators can be used to apply a user function to a `SeqVarData` object. Creating the iterator defines the sets of variants returned on every subsequent call to `iterateFilter()`. `iterateFilter()` returns `TRUE` if there are more variants remaining, and `FALSE` when all variants have been returned.

## Block iterators

The simplest type of iterator, a `SeqVarBlockIterator`, returns variants in consecutive blocks.

    library(SeqVarTools)

    ## Loading required package: SeqArray

    ## Loading required package: gdsfmt

    gds <- seqOpen(seqExampleFileName("gds"))
    seqData <- SeqVarData(gds)
    iterator <- SeqVarBlockIterator(seqData, variantBlock=500)

    ## # of selected variants: 500

    var.info <- list(variantInfo(iterator))
    i <- 2
    while(iterateFilter(iterator)) {
        var.info[[i]] <- variantInfo(iterator)
        i <- i + 1
    }

    ## # of selected variants: 500
    ## # of selected variants: 348
    ## # of selected variants: 0

    lapply(var.info, head)

    ## [[1]]
    ##   variant.id chr     pos ref alt
    ## 1          1   1 1105366   T   C
    ## 2          2   1 1105411   G   A
    ## 3          3   1 1110294   G   A
    ## 4          4   1 3537996   T   C
    ## 5          5   1 3538692   G   C
    ## 6          6   1 3541597   C   T
    ##
    ## [[2]]
    ##   variant.id chr      pos ref alt
    ## 1        501   7 48109509   C   T
    ## 2        502   7 72486435   G   C
    ## 3        503   7 72487157   A   C
    ## 4        504   7 72487452   G   A
    ## 5        505   7 94872711   G   C
    ## 6        506   7 94878932   G   A
    ##
    ## [[3]]
    ##   variant.id chr      pos ref alt
    ## 1       1001  17 30793147   G   A
    ## 2       1002  17 30793151   C   A
    ## 3       1003  17 30795794   G   A
    ## 4       1004  17 30796109   G   A
    ## 5       1005  17 30796359   C   T
    ## 6       1006  17 30796663   C   T

    seqResetFilter(seqData)

    ## # of selected samples: 90
    ## # of selected variants: 1,348

A filter can be applied before the iterator is created, and only variants included in the filter will be returned by the iterator.

    seqSetFilter(seqData, variant.sel=1:100)

    ## # of selected variants: 100

    iterator <- SeqVarBlockIterator(seqData, variantBlock=500)

    ## # of selected variants: 100

    var.info <- variantInfo(iterator)
    nrow(var.info)

    ## [1] 100

    iterateFilter(iterator)

    ## # of selected variants: 0

    ## [1] FALSE

    seqResetFilter(seqData)

    ## # of selected samples: 90
    ## # of selected variants: 1,348

## Range iterators

A `GRanges` object can be used to create a `SeqVarRangeIterator`, where every iteration returns the next range.

    library(GenomicRanges)

    ## Loading required package: stats4

    ## Loading required package: BiocGenerics

    ## Loading required package: generics

    ##
    ## Attaching package: 'generics'

    ## The following objects are masked from 'package:base':
    ##
    ##     as.difftime, as.factor, as.ordered, intersect, is.element, setdiff,
    ##     setequal, union

    ##
    ## Attaching package: 'BiocGenerics'

    ## The following objects are masked from 'package:stats':
    ##
    ##     IQR, mad, sd, var, xtabs

    ## The following object is masked from 'package:utils':
    ##
    ##     data

    ## The following objects are masked from 'package:base':
    ##
    ##     anyDuplicated, aperm, append, as.data.frame, basename, cbind,
    ##     colnames, dirname, do.call, duplicated, eval, evalq, Filter, Find,
    ##     get, grep, grepl, is.unsorted, lapply, Map, mapply, match, mget,
    ##     order, paste, pmax, pmax.int, pmin, pmin.int, Position, rank,
    ##     rbind, Reduce, rownames, sapply, saveRDS, scale, sequence, table,
    ##     tapply, transform, unique, unsplit, which.max, which.min

    ## Loading required package: S4Vectors

    ##
    ## Attaching package: 'S4Vectors'

    ## The following object is masked from 'package:utils':
    ##
    ##     findMatches

    ## The following objects are masked from 'package:base':
    ##
    ##     expand.grid, I, unname

    ## Loading required package: IRanges

    ## Loading required package: Seqinfo

    gr <- GRanges(seqnames=rep(1,3),
                  ranges=IRanges(start=c(1e6, 2e6, 3e6), width=1e6))
    iterator <- SeqVarRangeIterator(seqData, variantRanges=gr)

    ## # of selected variants: 3

    var.info <- list(variantInfo(iterator))
    i <- 2
    while(iterateFilter(iterator)) {
        var.info[[i]] <- variantInfo(iterator)
        i <- i + 1
    }

    ## # of selected variants: 0
    ## # of selected variants: 4
    ## # of selected variants: 0

    lapply(var.info, head)

    ## [[1]]
    ##   variant.id chr     pos ref alt
    ## 1          1   1 1105366   T   C
    ## 2          2   1 1105411   G   A
    ## 3          3   1 1110294   G   A
    ##
    ## [[2]]
    ## [1] variant.id chr        pos
    ## <0 rows> (or 0-length row.names)
    ##
    ## [[3]]
    ##   variant.id chr     pos ref alt
    ## 1          4   1 3537996   T   C
    ## 2          5   1 3538692   G   C
    ## 3          6   1 3541597   C   T
    ## 4          7   1 3541652   G   A

    seqResetFilter(seqData)

    ## # of selected samples: 90
    ## # of selected variants: 1,348

## Window iterators

Window iterators (`SeqVarWindowIterator`) are a special class of range iterators. When the object is created, the ranges are generated automatically with a specified width and step size, covering the entire genome.

    seqSetFilterChrom(seqData, include="22")

    ## # of selected variants: 23

    iterator <- SeqVarWindowIterator(seqData, windowSize=10000,
                                     windowShift=5000)

    ## # of selected variants: 2

    var.info <- list(variantInfo(iterator))
    i <- 2
    while(iterateFilter(iterator)) {
        var.info[[i]] <- variantInfo(iterator)
        i <- i + 1
    }

    ## # of selected variants: 3
    ## # of selected variants: 1
    ## # of selected variants: 1
    ## # of selected variants: 2
    ## # of selected variants: 4
    ## # of selected variants: 1
    ## # of selected variants: 2
    ## # of selected variants: 1
    ## # of selected variants: 2
    ## # of selected variants: 1
    ## # of selected variants: 1
    ## # of selected variants: 4
    ## # of selected variants: 1
    ## # of selected variants: 0

    lapply(var.info, head)

    ## [[1]]
    ##   variant.id chr      pos ref alt
    ## 1       1326  22 16042444   C   G
    ## 2       1327  22 16042793   A   G
    ##
    ## [[2]]
    ##   variant.id chr      pos ref alt
    ## 1       1326  22 16042444   C   G
    ## 2       1327  22 16042793   A   G
    ## 3       1328  22 16049306   T   C
    ##
    ## [[3]]
    ##   variant.id chr      pos ref alt
    ## 1       1328  22 16049306   T   C
    ##
    ## [[4]]
    ##   variant.id chr      pos ref alt
    ## 1       1329  22 17729354   G   A
    ##
    ## [[5]]
    ##   variant.id chr      pos ref alt
    ## 1       1330  22 18338811   C   T
    ## 2       1331  22 18338829   G   A
    ##
    ## [[6]]
    ##   variant.id chr      pos ref alt
    ## 1       1332  22 18348971   G   A
    ## 2       1333  22 18349075   A   G
    ## 3       1334  22 18349106   A   G
    ## 4       1335  22 18349495   G   T
    ##
    ## [[7]]
    ##   variant.id chr      pos ref alt
    ## 1       1336  22 20328280   G   A
    ##
    ## [[8]]
    ##   variant.id chr      pos ref  alt
    ## 1       1337  22 32000584   G    A
    ## 2       1338  22 32003125   C T,AT
    ##
    ## [[9]]
    ##   variant.id chr      pos ref alt
    ## 1       1339  22 32330460   G   A
    ##
    ## [[10]]
    ##   variant.id chr      pos ref alt
    ## 1       1340  22 38747766   A   G
    ## 2       1341  22 38747889   G   A
    ##
    ## [[11]]
    ##   variant.id chr      pos ref alt
    ## 1       1342  22 43657667   G   A
    ##
    ## [[12]]
    ##   variant.id chr      pos ref alt
    ## 1       1343  22 43670607   C   A
    ##
    ## [[13]]
    ##   variant.id chr      pos ref alt
    ## 1       1344  22 43690908   G   A
    ## 2       1345  22 43690970   C   T
    ## 3       1346  22 43691009   C   T
    ## 4       1347  22 43691073   G   A
    ##
    ## [[14]]
    ##   variant.id chr      pos ref alt
    ## 1       1348  22 48958933   A   G

    seqResetFilter(seqData)

    ## # of selected samples: 90
    ## # of selected variants: 1,348

## List iterators

A `SeqVarListIterator` can be used to specify particular variants to include in each iteration. The input is a `GRangesList`, and each list element defines an iteration set.

    gr <- GRangesList(
      GRanges(seqnames=rep(22,2),
              ranges=IRanges(start=c(16e6, 17e6), width=1e6)),
      GRanges(seqnames=rep(22,2),
              ranges=IRanges(start=c(18e6, 20e6), width=1e6)))
    iterator <- SeqVarListIterator(seqData, variantRanges=gr)

    ## # of selected variants: 4

    var.info <- list(variantInfo(iterator))
    i <- 2
    while(iterateFilter(iterator)) {
        var.info[[i]] <- variantInfo(iterator)
        i <- i + 1
    }

    ## # of selected variants: 7
    ## # of selected variants: 0

    lapply(var.info, head)

    ## [[1]]
    ##   variant.id chr      pos ref alt
    ## 1       1326  22 16042444   C   G
    ## 2       1327  22 16042793   A   G
    ## 3       1328  22 16049306   T   C
    ## 4       1329  22 17729354   G   A
    ##
    ## [[2]]
    ##   variant.id chr      pos ref alt
    ## 1       1330  22 18338811   C   T
    ## 2       1331  22 18338829   G   A
    ## 3       1332  22 18348971   G   A
    ## 4       1333  22 18349075   A   G
    ## 5       1334  22 18349106   A   G
    ## 6       1335  22 18349495   G   T

After the last iteration, any methods used on the iterator object will return 0 variants. The `resetIterator()` method can be used to reset an iterator back to the beginning.

    variantInfo(iterator)

    ## [1] variant.id chr        pos
    ## <0 rows> (or 0-length row.names)

    resetIterator(iterator)

    ## # of selected variants: 4

    variantInfo(iterator)

    ##   variant.id chr      pos ref alt
    ## 1       1326  22 16042444   C   G
    ## 2       1327  22 16042793   A   G
    ## 3       1328  22 16049306   T   C
    ## 4       1329  22 17729354   G   A

    seqClose(gds)