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

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

<!-- badges: start -->

<!-- badges: end -->

## Introduction

`ConSciR` provides tools for the analysis of cultural heritage preventive conservation data. It includes functions for environmental data analysis, humidity calculations, sustainability metrics, conservation risks, and data visualisations such as psychrometric charts. It is designed to support conservators, scientists, and engineers by streamlining common calculations and tasks encountered in heritage conservation workflows. The package is motivated by the framework outlined in Cosaert and Beltran et al. (2022) "Tools for the Analysis of Collection Environments" ["Tools for the Analysis of Collection Environments"](https://www.getty.edu/conservation/publications_resources/pdf_publications/tools_for_the_analysis_of_collection_environments.html "Getty Tools publication").

## Install and load

``` r
install.packages("ConSciR")
library(ConSciR)
```

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

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

# Alternatively
# 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)

This vignette provides a practical introduction to the package’s functionalities. For full details on all functions, see the package [Reference](https://bhavshah01.github.io/ConSciR/reference/index.html) manual or use `?function_name` within R.

## Examples

Load some useful packages:

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

### Add calculated values

Transform your dataset with the functions in ConSciR:

```{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(
    
    # Humidity functions
    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),
    
    # Conservation risks
    Mould_Growth_Rate_mm_day = calcMould_Zeng(Temp, RH, label = TRUE),
    Mould_Growth_Limit = calcMould_Zeng(Temp, RH), 
    Mould_Growth_Risk = ifelse(RH > Mould_Growth_Limit, "Mould risk", "No risk"),
    Mould_Growth_Index = calcMould_VTT(Temp, RH), 
    Lifetime = calcLM(Temp, RH), 
    Preservation_Index = calcPI(Temp, RH), 
    EMC_Wood = calcEMC_wood(Temp, RH),
    
    # Sustainability calculations 
    Temp_from_DP = calcTemp(RH, Dew_Point),
    RH_from_DP = calcRH_DP(Temp, Dew_Point),
    RH_from_AH = calcRH_AH(Temp, Absolute_Humidity),
    RH_if_2C_higher = calcRH_AH(Temp + 2, Absolute_Humidity)
    
  ) |>
  glimpse()


head(mydata) |> 
  tidy_TRHdata() |> # tidy
  add_time_vars() |> # add time factors 
  add_humidity_calcs() |> # add humidity values 
  add_conservation_calcs() |> # add conservation risks
  add_humidity_adjustments() # add environmental zones and RH adjustments

```

### Visualise and explore data

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 = "cyan4", alpha = 0.7) +
  # Add Dew Point line
  geom_line(aes(Date, DewPoint), color = "mediumvioletred", alpha = 0.7) +
  # 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 = "lightseagreen") +
  labs(title = "Mould Growth Index", y = "Mould Index", x = NULL) + 
  theme_bw()
```

### Psychrometric Chart

Create psychrometric charts from temperature and humidity data. The functions from the package can be used to change the calculations used.

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

head(mydata, 100) |>
  graph_psychrometric(
    LowT = 12, 
    HighT = 28,
    LowRH = 40, 
    HighRH = 70,
    data_alpha = 0.3,
    y_func = calcAH
  ) + 
  theme_classic()
```

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