README.qmd

---
title: "handwriterRF"
format: 
  html:
    theme: csafe.css
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

HandwriterRF is designed to assist forensic document examiners by performing a statistical analysis on two handwriting samples. One or both of the samples could be from unknown writers. Two hypotheses are considered:

$H_p: \text{The two documents were written by the same writer.}$ $H_d: \text{The two documents were written by different writers.}$

The statistical analysis produces a *score-based likelihood ratio (SLR)*. An SLR greater than one, indicates that the evidence supports $H_p$ over $H_d$, and the larger the SLR, the stronger the support. An SLR less than one, indicates that the evidence supports $H_d$ over $H_p$, and the closer the SLR is to zero, the stronger the support.

# Quick Start

## Installation

HandwriterRF requires R and RStudio IDE.

-   Install R from [POSIT](https://posit.co/download/rstudio-desktop/)
-   Install RStudio IDE from [POSIT](https://posit.co/download/rstudio-desktop/)

Install the handwriterRF R package. Open RStudio, navigate to the console window, and type

```{r, eval=FALSE}
install.packages("handwriterRF")
```

## Compare Two Handwriting Samples
### Calculate a Score-base Likelihood Ratio
Open RStudio, navigate to the console window, and load handwriterRF.
```{r}
library(handwriterRF)
```

The package includes 4 example handwriting samples from the [CSAFE Handwriting Database](https://forensicstats.org/handwritingdatabase/). Compare 2 of these samples. In this case, both samples are from writer 30.
```{r, message=FALSE}
sample1 <- system.file(file.path("extdata", "w0030_s01_pWOZ_r01.png"), package = "handwriterRF")
sample2 <- system.file(file.path("extdata", "w0030_s01_pWOZ_r02.png"), package = "handwriterRF")
slr <- calculate_slr(sample1, sample2)
```

If you would like to use your own handwriting samples, scan and save them as PNG images. 
```{r, eval=FALSE}
sample1 <- "path/to/your_sample1.png"
sample2 <- "path/to/your_sample2.png"
slr <- calculate_slr(sample1, sample2)
```

The result is a data frame:

-   *sample1_path* is the file path of the first sample.
-   *sample2_path* is the file path of the second sample.
-   *docname1* is the file name of the first sample.
-   *docname2* is the file name of the second sample.
-   *score* is the similarity score between the two samples.
-   *numerator* is the numerator value of the score-based likelihood ratio. Intuitively, the larger the value the more the similarity score looks like the reference same writer similarity scores.
-   *denominator* is the denominator value of the score-based likelihood ratio. Intuitively, the larger the value the more the similarity score looks like the reference different writers similarity scores.
-   *slr* is a score-based likelihood ratio that quantifies the strength of evidence in favor of same writer or different writer.

Display the slr data frame. We hide the file path columns here so that the data frame fits on this page.

```{r}
slr %>% dplyr::select(-sample1_path, -sample2_path)
```

### Interpret the Score-base Likelihood Ratio
View a verbal interpretation of the score-based likelihood ratio.
```{r, message=FALSE}
interpret_slr(slr)
```