---
title: "Getting Started with SuperIntervals"
output: rmarkdown::html_vignette
vignette: >
    %\VignetteIndexEntry{Getting Started with SuperIntervals}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{r setup-knitr, include = FALSE}
knitr::opts_chunk$set(
    collapse = TRUE,
    comment = "#>"
)
```

## Introduction

SuperIntervals provides fast interval intersection queries.
This is particularly useful for genomic analysis, time series data, and
any application requiring efficient range-based lookups.

Coordinates include both endpoints. Constructors require whole numbers in the
R integer range, excluding missing values. Search indices refer to internal
start-sorted order; hit order is unspecified. Maps mutate by reference and
cannot be restored from serialized external pointers. Query functions assume
valid inputs and a current index, without checking those conditions on each call.

## Basic Usage

```{r setup}
library(superintervalsr)
```

### Creating and Building an IntervalMap

```{r basic}
# Create a new IntervalMap
imap <- IntervalMap(c(10, 15, 30),
                        ends = c(20, 25, 40),
                        values = c("Gene A", "Gene B", "Gene C"))
```

Alternatively data can be added sequentially, followed by calling `build()`:

```{r basic_sequential}
# Create a new IntervalMap
imap <- IntervalMap()

# Add some intervals with associated values
add(imap, 10, 20, "Gene A")
add(imap, 15, 25, "Gene B")
add(imap, 30, 40, "Gene C")

# Build the index (required before queries)
build(imap)

```

### Searching for Overlaps

```{r search}
# Find all values that overlap with range 12-18
values <- search_values(imap, 12, 18)
print(values)

# Get the intervals (start, end) that overlap
keys <- search_keys(imap, 12, 18)
print(keys)

# Get complete information (start, end, value)
items <- search_items(imap, 12, 18)
print(items)

# Find all indices that overlap with range 12-18
indices <- search_idxs(imap, 12, 18)
print(indices)
```

### Query Statistics

```{r stats}
# Check if any intervals overlap a range
has_overlaps(imap, 5, 12)
has_overlaps(imap, 50, 60)

# Count overlapping intervals
count(imap, 12, 18)

# Sum inclusive intersection widths (overlaps counted independently)
coverage(imap, 10, 40)
```

### Accessing Individual Intervals

```{r access}
# Get interval at specific index
at(imap, 1)

# Get just the start position
starts_at(imap, 1)

# Get just the end position
ends_at(imap, 1)

# Get just the value
data_at(imap, 1)
```

## Set operations

All map-producing operations return already indexed maps:

```{r operations}
merged <- merge_overlaps(imap)
search_keys(merged, 1, 50)
gaps(merged, 1, 50)
expand(imap, 2, 2)
flank(imap, 2, 2)
unique_intervals(imap)
span(imap)
```

Adjacent intervals without an overlap remain separate when merging.
Intersection and difference retain left-side values; merge and union select one
representative value per merged region. Metadata ties are unspecified.

## Performance Tips

- Call `build()` after adding all intervals and before performing queries
- Use `reserve()` if you know the number of intervals in advance
- The IntervalMap is optimized for many queries on the same set of intervals

## Use Cases

SuperIntervals is ideal for:

- **Genomics**: Finding genes/features overlapping genomic regions
- **Time series**: Querying events within time ranges
- **Spatial analysis**: Range-based spatial queries
- **Data analysis**: Any scenario requiring fast interval overlap detection

## Session Information

```{r sessioninfo}
sessionInfo()
```