---
title: "ConSciR"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{ConSciR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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


<!-- badges: start -->

<!-- badges: end -->


## Introduction

`ConSciR` is an R package specifically designed to assist conservators, scientists, and engineers 
by providing a toolkit for performing calculations and streamlining common tasks in cultural 
heritage conservation.

## Install and load

You can install the development version of the package from GitHub using either the `pak` or `devtools` package:

``` r
install.packages("pak")
pak::pak("BhavShah01/ConSciR")
```

-or-

``` r
# install.packages("devtools")
devtools::install_github("BhavShah01/ConSciR")
```

Visit the package GitHub page for updates and source code: [ConSciR Github](https://github.com/BhavShah01/ConSciR)

## Examples

Load the necessary packages:

```{r load packages, message=FALSE, warning=FALSE}
# Load packages
library(ConSciR)
library(dplyr)
library(ggplot2)
```

### Add calculated values using `mutate`

Enrich your dataset with environmental metrics computed by ConSciR functions:

```{r table of calculated values, message=FALSE, warning=FALSE}
filepath <- data_file_path("mydata.xlsx")
mydata <- readxl::read_excel(filepath, sheet = "mydata")
mydata <- mydata |> filter(Sensor == "Room 1")


# Add calculated values using mutate
head(mydata) |> 
  mutate(
    Absolute_Humidity = calcAH(Temp, RH), 
    Dew_Point = calcDP(Temp, RH), 
    Mixing_Ratio = calcMR(Temp, RH), 
    Humidity_Ratio = calcHR(Temp, RH),
    Enthalpy = calcEnthalpy(Temp, RH), 
    Saturation_Vapour_Pressure = calcPws(Temp), 
    Actual_Vapour_Pressure = calcPw(Temp, RH), 
    Air_Density = calcAD(Temp, RH),
    Temp_calc = calcTemp(RH, Dew_Point),
    RH_AH_calc = calcRH_AH(Temp, Absolute_Humidity),
    RH_DP_calc = calcRH_DP(Temp, Dew_Point)
  ) |>
  glimpse()

```


### Visualise and explore data with calculations

Combine calculations and plotting to explore patterns visually:

```{r calculations to visualise the data, message=FALSE, warning=FALSE, fig.alt="visualisations"}

mydata |>
  # Calculate Absolute Humidity and Dew Point
  mutate(
    AbsHum = calcAH(Temp, RH),
    DewPoint = calcDP(Temp, RH)
  ) |>
  # Create base plot using graph_TRH function
  graph_TRH() +
  # Add Absolute Humidity line
  geom_line(aes(Date, AbsHum), color = "green") +
  # Add Dew Point line
  geom_line(aes(Date, DewPoint), color = "purple") +
  # Apply a theme
  theme_bw()

```


-   **Conservator tools: mould growth index**\
    Calculate mould growth index using **`calcMould_VTT()`** and visualise it alongside humidity data.

```{r mould_risk, message=FALSE, warning=FALSE, fig.alt="mould"}
mydata |>
  mutate(Mould = calcMould_VTT(Temp, RH)) |>
  ggplot() +
  geom_area(aes(Date, Mould), fill = "darkgreen", alpha = 0.5) +
  labs(title = "Mould Growth Index", 
       y = "Mould Index") + 
  theme_classic()
```



### Built-in psychrometric chart

Visualise the first 100 rows of the dataset with a psychrometric chart:

```{r psychrometric chart, message=FALSE, warning=FALSE, fig.alt="psychrometric_chart_example"}

head(mydata, 100) |>
  graph_psychrometric() + 
  theme_bw()
```

### Psychrometric Chart Customisation

Create tailored psychrometric charts by adjusting parameters such as temperature and humidity ranges, visual transparency, or y-axis metrics:

```{r psychrometric custom, message=FALSE, warning=FALSE, fig.alt="psychrometric_chart_custom"}

head(mydata, 100) |>
  graph_psychrometric(
    LowT = 10, 
    HighT = 28,
    LowRH = 20, 
    HighRH = 80,
    data_alpha = 0.3,
    y_func = calcAH
  ) + 
  theme_classic()
```

------------------------------------------------------------------------

This vignette provides a practical introduction to the package’s core functionalities. For full details on all functions, see the package Reference manual or use `?function_name` within R.