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

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

```{r setup}
library(oeis.tools)
```

## Introduction

`oeis.tools` is an R interface to the Online Encyclopedia of Integer Sequences (OEIS): it fetches sequence metadata and b-files, parses them into S3 objects, and plots terms with `ggplot2`.

## Fetching a Sequence

`Sequence(oeis_id)` fetches and parses an OEIS entry from the JSON API.

```{r fetch-example, eval = FALSE}
# Fetch the Fibonacci sequence
fib <- Sequence("A000045")

# Access basic information
fib$id
fib$name
```

## Working with B-files

B-files contain more terms of a sequence than the main OEIS entry, often thousands.

```{r bfile-example, eval = FALSE}
# Get b-file data for Prime numbers
primes_bfile <- BFile("A000040")

# Access the data
data <- get_bfile_data(primes_bfile)
length(data)
```

## Visualization

`plot_data()` builds a `ggplot2` line or scatter plot from a `BFile`.

```{r plot-example, eval = FALSE}
# Plot the first 100 terms of the Fibonacci sequence from its b-file
plot_data(primes_bfile, n = 100, color = "darkgreen")
```

## Extracting Cross-References

`get_xref_ids()` extracts the OEIS ids referenced in a sequence's `xref` field:

```{r xref-example, eval = FALSE}
# Get related sequences for Fibonacci
get_xref_ids(fib)
```

## Keyword Descriptions

`oeis_keyword_description()` looks up the description text for an OEIS keyword tag:

```{r keyword-example}
oeis_keyword_description("core")
oeis_keyword_description("nice")
```

## Arbitrary-Precision Values

Sequence and b-file terms are stored as `gmp::bigz` values, so terms with
hundreds of digits are never truncated. `plot_data()` and `plot.Sequence()`
detect when a value overflows double precision and automatically switch to a
signed log10 magnitude scale.

```{r bignum-example, eval = FALSE}
bfile <- BFile("A000040")
get_bfile_indices(bfile)[1:5]
get_bfile_data(bfile)[1:5]
```

## B-file Metadata and Creation

`get_bfile_info()` summarizes the b-file attached to a `Sequence` (length,
first/last/min/max terms), and `create_bfile()` writes a vector of values out
to disk in the standard b-file format:

```{r bfile-info-example, eval = FALSE}
get_bfile_info(fib)

create_bfile("A999999", data = c(1, 1, 2, 3, 5, 8), offset = 0,
             output_path = tempdir())
```

## Citing a Sequence

`get_bibtex()` builds a BibTeX `@misc` entry for an OEIS sequence:

```{r bibtex-example, eval = FALSE}
cat(get_bibtex(fib))
```

## Graph Images

`get_graph_png()` downloads the OEIS-rendered graph image for a sequence as
raw PNG bytes, cached on the `Sequence` object after the first call:

```{r graph-example, eval = FALSE}
png_bytes <- get_graph_png(fib)

# Displays inline under Jupyter/IRkernel; otherwise returns the raw bytes
get_graph_image(fib)
```