---
title: "Insulin Sensitivity Indices Calculator"
author: "Sufyan Suleman"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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


# Insulin Sensitivity Indices Calculator

The 'isi_calculator' function is a comprehensive tool designed to calculate a wide array of surrogate insulin sensitivity indices. This vignette provides a detailed guide on installing the package, understanding its usage, and interpreting the output effectively.

## Installation

Before using 'isi_calculator'function from the 'InsuSensCalc' package, ensure that the necessary dependencies are installed and loaded into your R session for example: dplyr, magrittr and tibble.


Additionally, you need to install the 'InsuSensCalc' package itself. If It is available on CRAN, install it using:

install.packages("InsuSensCalc")


Or, if it's not on CRAN, you can install it directly from its repository, for example, GitHub:
using devtools::install_github("sufyansuleman/InsuSensCalc")


## Usage

The 'isi_calculator' function is designed to be flexible, accommodating various types of input data related to insulin sensitivity calculations:

- **Fasting:** Requires fasting glucose and insulin levels.
- **OGTT:** Requires glucose and insulin levels at multiple time points post-glucose load (e.g., 30 and 120 minutes).
- **Adipose Tissue (adipo):** Requires measurements related to adipose tissue, such as triglycerides and HDL cholesterol.
- **Tracer and DXA (tracer_dxa):** Includes specialized indices involving tracer measurements and dual-energy X-ray absorptiometry (DXA).

### Preparing Your Data

Your input dataframe should include columns corresponding to the required measurements for your chosen calculation categories. The column names should match the expected names exactly.

### Function Parameters

- `data`: The input dataframe.
- `category`: A character vector specifying which indices to calculate. Available options: `"fasting"`, `"ogtt"`, `"adipo"`, and `"tracer_dxa"`.

### Advanced Details

The function includes automatic unit conversions for relevant variables and handles missing data gracefully, either skipping calculations for missing variables or setting indices to NA when applicable.

### Example Usage

```{r example-usage}
# Load the package
library(InsuSensCalc)

# Load your data
# example_data <- read.csv("path/to/your/data.csv")

# Sample usage of the function
result_fasting <- isi_calculator(example_data, category = "fasting")
result_ogtt <- isi_calculator(example_data, category = "ogtt")
result_adipo <- isi_calculator(example_data, category = "adipo")
result_combined <- isi_calculator(example_data, category = c("fasting", "ogtt", "adipo", "tracer_dxa"))

# Print a result to view
print(result_fasting)
```

## Output Interpretation

The output of 'isi_calculator' is a dataframe containing the calculated indices for each specified category. These values are provided without normalization or transformation. It is advisable to normalize these values according to your analysis needs, especially when planning to conduct statistical testing or visualization.

## Conclusion

The 'InsuSensCalc' package and its 'isi_calculator' function offer a robust solution for calculating insulin sensitivity indices from a variety of data types. By following the guidelines in this vignette, you can effectively utilize this tool for your research or clinical assessments related to insulin sensitivity and metabolic health.