README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# intermittent

<!-- badges: start -->
![](https://camo.githubusercontent.com/ea6e0ff99602c3563e3dd684abf60b30edceaeef/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6966656379636c652d6578706572696d656e74616c2d6f72616e67652e737667)
<!-- badges: end -->

The goal of intermittent is to assist IR analysts with 'term' data formats originating in various student information systems (SIS). Currently, two origins are supported: SIMS and Campus Solutions.

intermittent is built [with vctrs, a package that makes it easy to create S3 vectors.](https://github.com/r-lib/vctrs)

```{r echo=FALSE}
knitr::kable(data.frame(
  Sims = c(20124, 20132, 20133, 20134),
  CS = c(2127, 2133, 2135, 2137),
  Label = c("Fall 2012", "Spring 2013", "Summer 2013", "Fall 2013")
))
```


## Installation

You can install intermittent from GitHub with:

``` r
remotes::install_github("ir-sfsu/intermittent")
```

## The 'term' class

Create a term object with `term` and indicate an origin.

```{r example}
library(intermittent)
x <- term(2123, origin = "cs")
x
attributes(x)
```

## Arithmetic

R 'understands' term 2123 to be equivilent of 'Spring 2012'.

```{r error=TRUE}
### Increment the term
x + 1 # To Fall 2012
x + 2 # To Spring 2013
x + 5 # To Fall 2014

x - 1 # To Fall 2011
x - 3 # To Fall 2010

### Comparison
y <- term(2133, "cs")
x < y 
```


Subtract a term from a term to count the terms in-between. This is useful when counting the number of terms to graduation.

```{r}
grad_term <- term(20182, "sims") # Spring 2018
matric_term <- term(20144, "sims") # Fall 2014
grad_term - matric_term 
```

## Helpers

Get the label, academic year, or calendar year for any term object.

```{r}
label_term(x)
acad_year(x)
cal_year(x)
```

Create a sequence of terms with a `seq` method.

```{r}
# Fall 2010 to Spring 2016 with a "sims" origin
sims_terms <- seq(term(20104), 20162)
sims_terms

min(sims_terms)
max(sims_terms)
median(sims_terms) # Retrieve the 'middle' term
range(sims_terms) # Retrieve the min/max
```

Use with packages like `dplyr`.

```{r warning=FALSE, message=FALSE}
library(dplyr)
library(tibble)

tibble(term = c(2123, 2127, 2133, 2137)) %>% 
  mutate(
    term = as_term(term, "cs"),
    second_term = term + 1,
    grad_term = as_term(2163, "cs"),
    terms_to_degree = grad_term - term, # or term_duration(grad_term, term)
    term_label = label_term(term),
    academic_year = acad_year(term),
    year = cal_year(term)
  )
```

## Other helpers and operators

```{r}
fall16 <- term(2167, origin = "cs")
spring20 <- term(2203, origin = "cs")
label_term(fall16)
label_term(spring20)

# Get next 5 terms
label_term(get_next(fall16, 5))

# Get last 5 terms
label_term(get_last(spring20, 5))

# Get next 5 fall terms
label_term(fall16 %+F% 5)

# Get last 5 spring terms
label_term(spring20 %-S% 5)
```

## Package Options - Include Summer Terms?

You may have noticed that the default sequencing, addition, and subtraction do not account for Summer terms. To change this behavior, change the package options:

```{r}
getOption("intermittent.use_terms")
seq(term(2127, "cs"), 2173)

options(intermittent.use_terms = "all")
seq(term(2127, "cs"), 2173)
```

## Future work

* Other SIS origins?
* Other methods?
* Tests