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%"
)
```

# juncture

<!-- badges: start -->
[![R-CMD-check](https://github.com/johnmackintosh/juncture/workflows/R-CMD-check/badge.svg)](https://github.com/johnmackintosh/juncture/actions)
[![Codecov test coverage](https://codecov.io/gh/johnmackintosh/juncture/branch/master/graph/badge.svg)](https://app.codecov.io/gh/johnmackintosh/juncture?branch=master)
<!-- badges: end -->

The goal of juncture is to create census tables of people or resources by period, given a start and end date, without reliance on access to a database or writing SQL.

Consider the scenario where you need to know how many patients were 'IN' hospital.
Some typical questions might be:  
- How many patients were in the hospital at 10 AM yesterday?  
- How many were in during each 15 minute spell between 2pm and 6pm?  
- How many were in during the last week, by hour?  


This package aims to make answering these questions easier and quicker.

No SQL? No problem!

If you have time in, time out, a unique identifier, and optionally, a grouping variable to track moves between departments or changes in status, this package will tell you how many individuals or resources were 'IN' / 'OPEN' at any time, at whatever granularity you need.

## Installation

```r
# install.packages("remotes") # if not already installed
remotes::install_github("johnmackintosh/juncture")
```

## The problem

The built-in dataset, ```beds``` shows the problem. We need a way to count the number of patients in the hospital, either by bed, or on an individual basis, by any time interval.

```{r check-dataset, echo=TRUE}
library(juncture)
beds
```


## Summary by hour

To obtain summary data for every hour, for all combined patient stays, we set ```results``` to ```totals```.  

The base date and base hour for each interval are supplied to enable easier filtering of the results.  

Here the output is restricted to ```2020-01-01``` using the generated ```base_date``` column:  

```{r example_hour, echo=TRUE}
library(juncture)
patient_count_hour <- juncture(beds, 
identifier = 'patient',
time_in = 'start_time', 
time_out = 'end_time', 
group_var = 'bed', 
time_unit = '1 hour', 
results = "total", 
uniques = TRUE)

patient_count_hour[base_date == '2020-01-01']
```


## Grouping by bed and hour

This example shows grouping results by bed and hour.  

```{r grouped, echo=TRUE}
library(juncture)
grouped <- juncture(beds, 
identifier = 'patient',
time_in = 'start_time', 
time_out = 'end_time', 
group_var = 'bed', 
time_unit = '1 hour',
results = "group", 
uniques = FALSE)

 # order the output by the  bed and start time: 
grouped[bed %chin% c('B', 'C')][,.(bed, base_date, base_hour, N)][order(bed,base_date, base_hour)][]
```


## Individual Level results

Use this option to enable further aggregation or analysis within R or other analytic tools.
The output contains 1 row per individual/ resource, per interval, for each interval within the respective date range.

```{r individual, echo = TRUE}
library(juncture)
patient_count_hour <- juncture(beds, 
identifier = 'patient',
time_in = 'start_time', 
time_out = 'end_time', 
group_var = 'bed', 
time_unit = '1 hour', 
results = "individual", 
uniques = TRUE)

head(patient_count_hour,10)

patient_count_hour[patient == 5,]
```







## General Help

- You must 'quote' your variables, for the time being at least..  

## Results
- Set results to 'individual' for 1 row per person / resource by interval, for each duration. 
- Set results to 'group' to get a count per group per interval.  
The 'uniques' argument will be set to FALSE (and any existing value will be over-ridden if necessary) to ensure each move in each group is counted.  
- Set results to 'total' for a summary of the data set - interval, base_hour and count.  


## Tracking moves within the same interval with 'uniques'
- To count individual people / resources ONLY, leave 'uniques' at the default value of 'TRUE'.  
- To count changes between groups during intervals, set uniques to 'FALSE'. 
For example, hospital patients who occupy beds in different wards or departments during an interval are accounted for in each location. They will be counted at least twice during the interval -  both in their initial location and their new location following the move.


## Timezones

- Everything is easier if you use "UTC" by default. 
You can attempt to coerce the final results yourself using lubridate::force_tz()  

To find your system timezone:

```r
Sys.timezone()
```

## Time Unit


See ? seq.POSIXt for valid values

E.G. '1 hour', '15 mins', '30 mins'


## Time Adjust

Want to count those in between 10:01 to 11:00? 
You can do that using 'time_adjust_period' - set it to 'start_min' and then set
'time_adjust_interval' to 1.


10:00 to 10:59?  
Yes, that's possible as well - set 'time_adjust_period' to 'end_min' and set 
'time_adjust_interval' as before. You can set these periods to any value, as long as it makes sense in relation to your chosen time_unit.

Here we adjust the start_time by 5 minutes

```{r example_start_min, echo=TRUE}
library(juncture)
patient_count_time_adjust <- juncture(beds, 
identifier = 'patient',
time_in = 'start_time', 
time_out = 'end_time', 
group_var = 'bed', 
time_unit = '1 hour', 
time_adjust_period = 'start_min',
time_adjust_value = 5,
results = "total", 
uniques = TRUE)

head(patient_count_time_adjust)
```

Valid values for time_adjust_period are 'start_min', 'start_sec', 'end_min' and 'end_sec'


## The hotel problem
How many patients are 'IN' the hotel each day

```{r hotel, echo  = TRUE}

check_in_date <- c('2010-01-01', '2010-01-02' ,'2010-01-01', '2010-01-08', 
                   '2010-01-08', '2010-01-15', '2010-01-15', '2010-01-16', '2010-01-19', '2010-01-22')
check_out_date <- c('2010-01-07', '2010-01-04' ,'2010-01-09', '2010-01-21', 
                    '2010-01-11', '2010-01-22', NA, '2010-01-20', '2010-01-25', '2010-01-29')
Person = c("John", "Smith", "Alex", "Peter", "Will", "Matt", "Tim", "Kevin", "Tom", "Adam")

checkin <- as.POSIXct(as.Date(check_in_date))
checkout <- as.POSIXct(as.Date(check_out_date))
hotel <- data.frame(checkin, checkout, Person)

hotel_occupancy <- juncture(hotel, 
         identifier = "Person",
         time_in = "checkin",
         time_out  = "checkout", 
         time_unit = '1 day',
         results = 'total')

# just show the dates and number 'IN'
hotel_occupancy[,.(base_date, N)]
```