### Install SurvdigitizeR Development Version from GitHub

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/index.html

Installs the development version of the SurvdigitizeR package directly from its GitHub repository. This requires the 'devtools' package to be installed.

```r
devtools::install_github("Pechli-Lab/SurvdigitizeR")
```

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

### Install SurvdigitizeR Locally

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/index.html

Installs the SurvdigitizeR package from a local source, typically after cloning the project repository. This method also requires the 'devtools' package.

```r
library(devtools)
install()
```

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

### R Function: range_detect for Pixel to Data Mapping

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/range_detect.html

The range_detect function maps pixel X and Y coordinates to time and survival values, respectively. It requires the output from previous digitization steps (step1_fig, step2_axes) and detailed information about the X and Y axes, including their start, end, and increment values. The function returns a list containing the pixel origins and increments for both axes, crucial for accurate data extraction.

```R
range_detect(
  step1_fig,
  step2_axes,
  x_start,
  x_end,
  x_increment,
  y_start,
  y_increment,
  y_end,
  y_text_vertical
)
```

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

### Load Libraries for Survival Curve Digitization (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/articles/Example-digitization.html

Loads essential R libraries required for image digitization, file path management, plotting, image handling, and data manipulation. These libraries are dependencies for the SurvdigitizeR package functions.

```r
library(SurvdigitizeR)
library(here)
library(ggplot2)
library(jpeg)
library(dplyr)
```

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

### Digitize Survival Curve from Image (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/articles/Example-digitization.html

Digitizes survival curves from a specified image file using the survival_digitize function from SurvdigitizeR. It takes the image path and parameters like the number of curves, censoring status, x-axis range and increments, and y-axis range and increments as input. Returns a data frame with digitized survival data.

```r
out1 <- SurvdigitizeR::survival_digitize(img_path = here::here("vignettes", "KMcurve.png"), num_curves = 2, censoring = F,
 x_start = 0, x_end = 10, x_increment = 1, y_start = 0, y_increment = 0.25, y_end = 1, y_text_vertical = T)
```

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

### img_read - Image Loading and Conversion

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Loads JPEG, JPG, or PNG image files and converts them to HSL (Hue/Saturation/Lightness) format for processing. Handles grayscale images by converting to RGB, removes alpha channels from RGBA images, resizes large images to maximum 1500 pixels, and flips the image vertically to correct raster orientation.

```APIDOC
## img_read - Image Loading and Conversion

### Description
Loads JPEG, JPG, or PNG image files and converts them to HSL (Hue/Saturation/Lightness) format for processing. Handles grayscale images by converting to RGB, removes alpha channels from RGBA images, resizes large images to maximum 1500 pixels, and flips the image vertically to correct raster orientation.

### Method
`img_read(path)`

### Parameters
* `path` (character) - The file path to the image (JPEG, JPG, or PNG).

### Request Example
```r
library(SurvdigitizeR)

# Load and convert image to HSL format
fig_hsl <- img_read(path = "path/to/survival_curve.png")

# Example with error handling
tryCatch({
  fig_hsl <- img_read(path = "survival_curve.jpg")
  print("Image loaded successfully")
}, error = function(e) {
  print(paste("Error loading image:", e$message))
})
```

### Response
#### Success Response (200)
- `fig_hsl` (array) - A 3D array with dimensions [height, width, 3]. The third dimension contains: [1] = hue (0-360), [2] = saturation (0-1), [3] = lightness (0-1).
```

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

### Image Loading and Conversion: img_read

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Loads JPEG, JPG, or PNG image files and converts them to HSL (Hue/Saturation/Lightness) format for processing. It handles grayscale and RGBA images, resizes large images, and corrects raster orientation. The function returns a 3D array representing the image in HSL color space.

```r
library(SurvdigitizeR)

# Load and convert image to HSL format
fig_hsl <- img_read(path = "path/to/survival_curve.png")

# Returns 3D array with dimensions [height, width, 3]
# Third dimension contains: [1] = hue (0-360), [2] = saturation (0-1), [3] = lightness (0-1)
dim(fig_hsl)
# [1] 800 1200 3

# Access individual channels
hue_channel <- fig_hsl[,,1]
saturation_channel <- fig_hsl[,,2]
lightness_channel <- fig_hsl[,,3]

# Example with error handling
tryCatch({
  fig_hsl <- img_read(path = "survival_curve.jpg")
  print("Image loaded successfully")
}, error = function(e) {
  print(paste("Error loading image:", e$message))
})
```

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

### Visualize Digitized Survival Data (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/articles/Example-digitization.html

Visualizes the digitized survival data using ggplot2. It plots the time and survival probability ('St') for each curve, colored by curve group. Requires the 'out1' data frame generated by survival_digitize and the dplyr package for data manipulation.

```r
out1 %>$
  ggplot(aes(x = time, y = St, color = as.factor(curve), group = curve)) +
  geom_step() + theme_bw()
```

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

### Digitize Survival Curve from Image using SurvdigitizeR

Source: https://github.com/pechli-lab/survdigitizer/blob/master/README.md

Demonstrates the core functionality of the SurvdigitizeR package by digitizing a survival curve from a PNG image. It specifies image path, number of curves, x and y-axis ranges and increments, and censoring status. Requires the 'here' package for path management.

```r
library(SurvdigitizeR)
library(here)

survival_digitize(img_path = here("vignettes","KMcurve.png"),
                                  num_curves = 2,
                                  x_start = 0,
                                  x_end = 10,
                                  x_increment = 1,
                                  y_start = 0,
                                  y_end = 1,
                                  y_increment = 0.25,
                                  y_text_vertical =  T,
                                  censoring = F)
```

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

### Visualize and Analyze Digitized Survival Data (R)

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Demonstrates how to visualize and perform basic analysis on the digitized survival data extracted by SurvdigitizeR. This includes creating survival curves using ggplot2 and calculating median survival times using dplyr. The output is suitable for further statistical analysis.

```r
# Visualize results
library(ggplot2)
ggplot(final_data, aes(x = time, y = St, color = factor(curve))) +
  geom_step() +
  labs(x = "Time", y = "Survival Probability", color = "Curve") +
  theme_minimal()

# Export to CSV for further analysis
write.csv(final_data, "digitized_survival_data.csv", row.names = FALSE)

# Calculate median survival time for each curve
library(dplyr)
final_data %>%
  group_by(curve) %>%
  filter(St <= 0.5) %>%
  summarise(median_survival = min(time))
```

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

### Digitize Kaplan-Meier Curve using SurvdigitizeR

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/index.html

Demonstrates the core functionality of the SurvdigitizeR package by digitizing a Kaplan-Meier curve image. It takes the image path and various parameters to define the curve's axes and characteristics as input. The output is time-of-event data.

```r
library(SurvdigitizeR)
library(here)

survival_digitize(img_path = here("vignettes","KMcurve.png"),
                                      num_curves = 2,
                                      x_start = 0,
                                      x_end = 10,
                                      x_increment = 1,
                                      y_start = 0,
                                      y_end = 1,
                                      y_increment = 0.25,
                                      y_text_vertical =  T,
                                      censoring = F)
```

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

### Survival Digitization Function

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/survival_digitize.html

The `survival_digitize` function is a wrapper for the end-to-end digitization process of survival curves from an image.

```APIDOC
## POST /survival_digitize

### Description
This endpoint processes an image file to extract survival curve data. It handles various parameters for image preprocessing, OCR, and curve digitization.

### Method
POST

### Endpoint
/survival_digitize

### Parameters
#### Request Body
- **img_path** (string) - Required - Location of the image file.
- **bg_lightness** (numeric) - Optional - Lightness threshold between 0 and 1 for background removal. Default is 0.3.
- **attempt_OCR** (boolean) - Optional - Whether to attempt Optical Character Recognition for word removal. Default is FALSE.
- **word_sensitivity** (numeric) - Optional - Sensitivity setting for OCR word removal. Default is 30.
- **num_curves** (integer) - Required - The number of survival curves present in the image.
- **censoring** (boolean) - Optional - Whether censoring is represented by black marks. Default is TRUE.
- **x_start** (numeric) - Required - The lowest value on the X-axis.
- **x_end** (numeric) - Required - The highest value on the X-axis.
- **x_increment** (numeric) - Required - The increment value for X-axis ticks (including minor ticks).
- **y_start** (numeric) - Required - The lowest value on the Y-axis.
- **y_end** (numeric) - Required - The highest value on the Y-axis.
- **y_increment** (numeric) - Required - The increment value for Y-axis ticks (including minor ticks).
- **y_text_vertical** (boolean) - Required - Indicates if Y-axis labels are oriented vertically (TRUE) or horizontally (FALSE).
- **nr_neighbors** (integer) - Optional - Number of neighbors for k-nearest neighbors (knn) pixel grouping. Default is 50.
- **enhance** (boolean) - Optional - Whether to convert HSL channels to the same scale. Default is FALSE.
- **impute_size** (numeric) - Optional - Size parameter for imputation.

### Request Example
```json
{
  "img_path": "/path/to/your/image.jpg",
  "bg_lightness": 0.1,
  "attempt_OCR": false,
  "num_curves": 2,
  "censoring": true,
  "x_start": 0,
  "x_end": 10,
  "x_increment": 1,
  "y_start": 0,
  "y_end": 1,
  "y_increment": 0.2,
  "y_text_vertical": true,
  "nr_neighbors": 50,
  "enhance": false,
  "impute_size": 0
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the digitized curve.
- **times** (numeric) - Time values corresponding to the survival curve.
- **St** (numeric) - Survival probability values (S(t)).
- **curve** (integer) - Identifier for the specific curve if multiple curves are present.

#### Response Example
```json
{
  "data": [
    {
      "id": "curve_1_segment_1",
      "times": [0.0, 1.5, 3.2, 5.0],
      "St": [1.0, 0.9, 0.75, 0.6],
      "curve": 1
    },
    {
      "id": "curve_1_segment_2",
      "times": [5.0, 6.1, 7.8, 9.5],
      "St": [0.6, 0.55, 0.4, 0.3],
      "curve": 1
    },
    {
      "id": "curve_2_segment_1",
      "times": [0.0, 1.0, 2.5, 4.0],
      "St": [1.0, 0.95, 0.8, 0.7],
      "curve": 2
    }
  ]
}
```

#### Error Response (400/500)
- **error** (string) - Description of the error that occurred.
```

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

### Load Image into Array (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/img_read.html

The img_read function loads an image file (JPEG, JPG, or PNG) from a specified path and converts it into an array of pixels in HSL format. This is the primary step for image processing within the SurvdigitizeR package.

```r
img_read(path)

# Example:
# img_read(path = "~/curve1.jpeg")
```

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

### Main Digitization Function: survival_digitize

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

The primary wrapper function that orchestrates the complete end-to-end digitization pipeline for Kaplan-Meier survival curves. It processes an image file through all transformation steps and returns a structured dataframe containing time points and survival probabilities. Dependencies include the 'SurvdigitizeR' and 'here' R packages.

```r
library(SurvdigitizeR)
library(here)

# Digitize a two-curve survival plot with standard parameters
result <- survival_digitize(
  img_path = here("vignettes", "KMcurve.png"),
  num_curves = 2,
  x_start = 0,
  x_end = 10,
  x_increment = 1,
  y_start = 0,
  y_end = 1,
  y_increment = 0.25,
  y_text_vertical = TRUE,
  censoring = FALSE
)

# Result is a dataframe with columns: id, time, St, curve
head(result)
#   id time   St curve
#   1  0.0  1.00     1
#   2  0.5  1.00     1
#   3  1.0  0.95     1
#   4  1.5  0.95     1
#   5  2.0  0.87     1
#   6  2.5  0.87     1

# Advanced usage with OCR text removal and enhanced color detection
result_advanced <- survival_digitize(
  img_path = "survival_plot.jpg",
  bg_lightness = 0.1,
  attempt_OCR = TRUE,
  word_sensitivity = 30,
  num_curves = 3,
  censoring = TRUE,
  x_start = 0,
  x_end = 60,
  x_increment = 5,
  y_start = 0,
  y_end = 100,
  y_increment = 10,
  y_text_vertical = FALSE,
  nr_neighbors = 50,
  enhance = TRUE,
  impute_size = 10,
  line_censoring = TRUE
)
```

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

### SurvdigitizeR Citation in BibTeX Format

Source: https://github.com/pechli-lab/survdigitizer/blob/master/README.md

Provides the citation for the SurvdigitizeR package in BibTeX format, commonly used for academic referencing in LaTeX documents. It includes author information, journal details, volume, issue, pages, year, publisher, and DOI.

```bibtex
@article{zhang2024survdigitizer,
  title={Survdigitizer: an algorithm for automated survival curve digitization},
  author={Zhang, Jasper Zhongyuan and Rios, Juan David and Pechlivanoglou, Tilemanchos and Yang, Alan and Zhang, Qiyue and Deris, Dimitrios and Cromwell, Ian and Pechlivanoglou, Petros},
  journal={BMC Medical Research Methodology},
  volume={24},
  number={1},
  pages={147},
  year={2024},
  publisher={BioMed Central},
  doi={10.1186/s12874-024-02273-8}
}
```

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

### survival_digitize - Main Digitization Function

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

The primary wrapper function that orchestrates the complete end-to-end digitization pipeline for Kaplan-Meier survival curves. It processes an image file through all transformation steps and returns a structured dataframe containing time points and survival probabilities for each identified curve.

```APIDOC
## survival_digitize - Main Digitization Function

### Description
Primary wrapper function that orchestrates the complete end-to-end digitization pipeline for Kaplan-Meier survival curves. It processes an image file through all transformation steps and returns a structured dataframe containing time points and survival probabilities for each identified curve.

### Method
`survival_digitize()`

### Parameters
* `img_path` (character) - Path to the image file (JPEG or PNG).
* `num_curves` (integer) - The number of survival curves present in the image.
* `x_start` (numeric) - The starting value of the x-axis.
* `x_end` (numeric) - The ending value of the x-axis.
* `x_increment` (numeric) - The increment step for the x-axis.
* `y_start` (numeric) - The starting value of the y-axis.
* `y_end` (numeric) - The ending value of the y-axis.
* `y_increment` (numeric) - The increment step for the y-axis.
* `y_text_vertical` (logical) - Whether the y-axis labels are oriented vertically.
* `censoring` (logical) - Whether to detect and mark censoring events.
* `bg_lightness` (numeric) - Lightness threshold for background detection (0-1).
* `attempt_OCR` (logical) - Whether to attempt Optical Character Recognition for text removal.
* `word_sensitivity` (integer) - Sensitivity parameter for OCR word detection.
* `nr_neighbors` (integer) - Number of neighbors for k-nearest neighbors algorithm.
* `enhance` (logical) - Whether to enhance image features for better curve detection.
* `impute_size` (integer) - Size parameter for imputation of missing curve points.
* `line_censoring` (logical) - Whether to detect censoring events on the curve lines.

### Request Example
```r
library(SurvdigitizeR)
library(here)

# Digitize a two-curve survival plot with standard parameters
result <- survival_digitize(
  img_path = here("vignettes", "KMcurve.png"),
  num_curves = 2,
  x_start = 0,
  x_end = 10,
  x_increment = 1,
  y_start = 0,
  y_end = 1,
  y_increment = 0.25,
  y_text_vertical = TRUE,
  censoring = FALSE
)

# Advanced usage with OCR text removal and enhanced color detection
result_advanced <- survival_digitize(
  img_path = "survival_plot.jpg",
  bg_lightness = 0.1,
  attempt_OCR = TRUE,
  word_sensitivity = 30,
  num_curves = 3,
  censoring = TRUE,
  x_start = 0,
  x_end = 60,
  x_increment = 5,
  y_start = 0,
  y_end = 100,
  y_increment = 10,
  y_text_vertical = FALSE,
  nr_neighbors = 50,
  enhance = TRUE,
  impute_size = 10,
  line_censoring = TRUE
)
```

### Response
#### Success Response (200)
- `result` (data.frame) - A dataframe with columns: `id`, `time`, `St` (survival probability), and `curve`.
```

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

### Map Pixel Coordinates to Axis Scales - R

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Detects how pixel coordinates map to actual time and survival values by reading axis labels using OCR. It identifies tick mark locations and uses Tesseract OCR to recognize text, calculating conversion ratios for both axes. The function requires intermediate results from `axes_identify` and user-defined axis range parameters.

```r
library(SurvdigitizeR)

# After loading image and identifying axes
fig_hsl <- img_read(path = "survival_curve.png")
axes_result <- axes_identify(fig_hsl = fig_hsl, bg_lightness = 0.1)

# Detect axis scales with OCR
range_list <- range_detect(
  step1_fig = axes_result$step_1,
  step2_axes = axes_result$axes,
  x_start = 0,
  x_end = 10,
  x_increment = 1,
  y_start = 0,
  y_end = 1,
  y_increment = 0.25,
  y_text_vertical = TRUE
)

# Returns list with pixel-to-value conversion parameters
str(range_list)

```

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

### Digitize Survival Curves using survival_digitize (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/survival_digitize.html

The survival_digitize function is a wrapper for the end-to-end process of digitizing survival curves from images. It takes an image path and various parameters to control background removal, OCR, axis scaling, and curve identification. It returns a dataframe with digitized survival data ('id', 'times', 'St', 'curve').

```r
survival_digitize(
  img_path,
  bg_lightness = 0.3,
  attempt_OCR = FALSE,
  word_sensitivity = 30,
  num_curves,
  censoring = FALSE,
  x_start,
  x_end,
  x_increment,
  y_start,
  y_end,
  y_increment,
  y_text_vertical,
  nr_neighbors = 20,
  enhance = FALSE,
  impute_size = 0
)
```

```r
if (FALSE) {
  survival_digitize(
    img_path = here::here("OS.jpg"),
    bg_lightness = 0.1,
    attempt_OCR = FALSE,
    num_curves = 2,
    x_start = 0,
    x_end = 10,
    x_increment = 1,
    y_start = 0,
    y_end = 1,
    y_increment = 0.2,
    y_text_vertical = TRUE
  )
}
```

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

### fig_clean - Background and Text Removal

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Removes background pixels and optionally removes text using OCR to isolate curve pixels. Filters pixels based on lightness threshold and uses Tesseract OCR to detect and remove text labels from the plot area.

```APIDOC
## fig_clean - Background and Text Removal

### Description
Removes background pixels and optionally removes text using OCR to isolate curve pixels. Filters pixels based on lightness threshold and uses Tesseract OCR to detect and remove text labels from the plot area.

### Method
`fig_clean(fig_hsl, bg_lightness, attempt_OCR)`

### Parameters
* `fig_hsl` (array) - The HSL formatted image array, typically output from `axes_identify()`.
* `bg_lightness` (numeric) - Lightness threshold for identifying background pixels (0-1).
* `attempt_OCR` (logical) - If TRUE, attempts to use Tesseract OCR to remove text elements from the image.

### Request Example
```r
library(SurvdigitizeR)

# Assuming fig_hsl and axes_result are available from previous steps
# fig_hsl <- axes_result$fig.hsl 

# Clean background with default settings
cleaned_fig <- fig_clean(fig_hsl = fig_hsl, bg_lightness = 0.1)

# Clean background and attempt OCR text removal
cleaned_fig_ocr <- fig_clean(fig_hsl = fig_hsl, bg_lightness = 0.1, attempt_OCR = TRUE)
```

### Response
#### Success Response (200)
- `cleaned_fig` (array) - The cleaned HSL formatted image array with background and potentially text removed.
```

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

### Summarize Survival Data Frame (R)

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Integrates isolated curve lines and axis scale mappings into a final survival data format. This function converts pixel coordinates to actual time and survival values, ensures survival probability bounds (0-1), and formats the output with id, time, St (survival), and curve columns. It requires the output from `lines_isolate` and `range_detect` functions.

```r
library(SurvdigitizeR)

# After line isolation and range detection
lines_vector <- lines_isolate(fig.curves = fig_resolved)
range_list <- range_detect(
  step1_fig = axes_result$step_1,
  step2_axes = axes_result$axes,
  x_start = 0, x_end = 10, x_increment = 1,
  y_start = 0, y_end = 1, y_increment = 0.25,
  y_text_vertical = TRUE
)

# Summarize into final dataframe
final_data <- fig_summarize(
  lines_vector = lines_vector,
  range_list = range_list,
  x_start = 0,
  y_start = 0,
  y_end = 1
)

# Returns structured survival data
head(final_data, 10)
#    id  time    St curve
#     1  0.00  1.00     1
#     2  0.15  1.00     1
#     3  0.15  0.95     1
#     4  0.89  0.95     1
#     5  0.89  0.87     1
#     6  1.45  0.87     1
#     7  1.45  0.82     1
#     8  2.10  0.82     1
#     9  2.10  0.78     1
#    10  2.75  0.78     1
```

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

### Clean Survival Curve Image Data - R

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Cleans a survival curve image by removing background pixels and optionally attempting OCR to remove text. It takes a processed HSL image and returns a dataframe of non-background pixels with their HSL values. Dependencies include the SurvdigitizerR package.

```r
library(SurvdigitizeR)

# After loading and cropping image
fig_hsl <- img_read(path = "survival_curve.png")
axes_result <- axes_identify(fig_hsl = fig_hsl, bg_lightness = 0.1)
cropped_fig <- axes_result$fig.hsl

# Basic cleaning without OCR
fig_df <- fig_clean(
  fig.hsl = cropped_fig,
  bg_lightness = 0.1,
  attempt_OCR = FALSE
)

# Returns dataframe with remaining non-background pixels
head(fig_df)
#     y   x   h    s    l
#   120 200 240 0.85 0.45
#   121 200 240 0.85 0.46
#   122 200 240 0.85 0.45

# Advanced cleaning with OCR text removal
fig_df_ocr <- fig_clean(
  fig.hsl = cropped_fig,
  bg_lightness = 0.1,
  attempt_OCR = TRUE,
  word_sensitivity = 30
)

# Higher word_sensitivity (e.g., 50) removes only high-confidence text
# Lower word_sensitivity (e.g., 20) removes more potential text patterns

```

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

### Background and Text Removal: fig_clean

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Removes background pixels and optionally removes text from the plot area to isolate curve pixels. It filters pixels based on a lightness threshold and can utilize Tesseract OCR for text removal. This function is a prerequisite for accurate curve tracing.

```r
library(SurvdigitizeR)

```

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

### Group Image Pixels by Color using k-medoids Clustering (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/color_cluster.html

The color_cluster function from the SurvdigitizeR package groups pixels of curves in an image based on their color using k-medoids clustering. It requires a dataframe with pixel coordinates (x, y) and HSL color values (h, s, l). The function returns a dataframe with an added 'group' column indicating the curve assignment for each pixel. Optional arguments control the number of curves, censoring detection, and HSL channel enhancement.

```r
color_cluster(fig.df, num_curves = 3, censoring = FALSE, enhance = FALSE)
```

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

### axes_identify - Axes Detection and Cropping

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Identifies the location of plot axes by analyzing pixel density patterns and crops the image to the plot area. Uses dual-threshold approach (0.9 and 0.6) to detect both standard and gray-colored axes, handles boxed plots with borders, and returns both cropped image and axis coordinates.

```APIDOC
## axes_identify - Axes Detection and Cropping

### Description
Identifies the location of plot axes by analyzing pixel density patterns and crops the image to the plot area. Uses dual-threshold approach (0.9 and 0.6) to detect both standard and gray-colored axes, handles boxed plots with borders, and returns both cropped image and axis coordinates.

### Method
`axes_identify(fig_hsl, bg_lightness)`

### Parameters
* `fig_hsl` (array) - The HSL formatted image array obtained from `img_read()`.
* `bg_lightness` (numeric) - Lightness threshold for background detection (0-1).

### Request Example
```r
library(SurvdigitizeR)

# Load image first
fig_hsl <- img_read(path = "survival_curve.png")

# Identify axes with default background threshold
axes_result <- axes_identify(fig_hsl = fig_hsl, bg_lightness = 0.1)

# Example with higher background threshold for darker backgrounds
axes_result_dark <- axes_identify(fig_hsl = fig_hsl, bg_lightness = 0.3)
```

### Response
#### Success Response (200)
- `axes_result` (list) - A list containing:
    - `$step_1`: Original figure (potentially with adjusted axis colors).
    - `$fig.hsl`: Cropped figure array containing only the plot area.
    - `$axes`: A list with `$xaxis` and `$yaxis` vectors indicating pixel coordinates of the axes.
```

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

### Separate Survival Curves by Color - R

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Groups pixels into distinct survival curves using k-medoids clustering based on HSL color values. It can optionally remove censoring marks and enhance clustering by equalizing HSL channel scales. The function takes a cleaned dataframe and returns a dataframe with group assignments for each pixel.

```r
library(SurvdigitizeR)

# After cleaning the figure
fig_df <- fig_clean(fig.hsl = cropped_fig, bg_lightness = 0.1)

# Cluster into multiple curves without censoring marks
fig_grouped <- color_cluster(
  fig.df = fig_df,
  num_curves = 2,
  censoring = FALSE,
  enhance = FALSE
)

# Returns dataframe with group assignments
head(fig_grouped)
#     x   y group
#   200 120     1
#   200 121     1
#   201 120     1
#   202 119     2

# For curves with censoring marks (black marks on curve)
fig_grouped_censored <- color_cluster(
  fig.df = fig_df,
  num_curves = 2,
  censoring = TRUE,
  enhance = FALSE
)

# Enhanced mode scales saturation and lightness for better color separation
fig_grouped_enhanced <- color_cluster(
  fig.df = fig_df,
  num_curves = 3,
  censoring = FALSE,
  enhance = TRUE
)

# Count pixels per curve
table(fig_grouped$group)
#    1    2
# 4521 3987

```

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

### Axes Detection and Cropping: axes_identify

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Identifies the location of plot axes within an HSL image and crops the image to the plot area. It uses a dual-threshold approach to detect axes and handles boxed plots. The function returns the cropped image and the pixel coordinates of the identified axes.

```r
library(SurvdigitizeR)

# Load image first
fig_hsl <- img_read(path = "survival_curve.png")

# Identify axes with default background threshold
axes_result <- axes_identify(fig_hsl = fig_hsl, bg_lightness = 0.1)

# Returns list with three elements:
# $step_1: original figure (potentially with adjusted axis colors)
# $fig.hsl: cropped figure array containing only plot area
# $axes: list with $xaxis and $yaxis vectors indicating pixel coordinates

# Access cropped figure
cropped_fig <- axes_result$fig.hsl
dim(cropped_fig)
# [1] 600 900 3

# Get axis coordinates
x_axis_pixels <- axes_result$axes$xaxis
y_axis_pixels <- axes_result$axes$yaxis

# Example with higher background threshold for darker backgrounds
axes_result_dark <- axes_identify(fig_hsl = fig_hsl, bg_lightness = 0.3)
```

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

### Isolate Single Y-Value per X-Coordinate for Curves - R

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Isolates the final singular y-value for each x-coordinate within each survival curve, ensuring a unique survival probability for each time point. It takes the resolved curve data and returns a list of dataframes, where each dataframe represents a single curve with its continuous path.

```r
library(SurvdigitizeR)

# After overlap detection
fig_resolved <- overlap_detect(fig.grp = fig_grouped, nr_neighbors = 20)

# Isolate single y-value per x-coordinate
lines_vector <- lines_isolate(fig.curves = fig_resolved)

# Returns list of dataframes, one per curve
length(lines_vector)
# [1] 2

# Examine first curve
head(lines_vector[[1]])
#   curve   x   y
#       1 150 580
#       1 151 580
#       1 152 579
#       1 153 578
#       1 154 577

# Examine second curve
head(lines_vector[[2]])
#   curve   x   y
#       2 150 520
#       2 151 519
#       2 152 518

# Check for continuous x-values
all(diff(lines_vector[[1]]$x) == 1)
# [1] TRUE

# Combine all curves for visualization
all_lines <- do.call(rbind, lines_vector)

```

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

### overlap_detect Function

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/overlap_detect.html

Detects potential overlap between curves and fills in gaps using KNN similarity.

```APIDOC
## overlap_detect

### Description
Detects potential overlap between curves and "fills in the gaps" using knn similarity.

### Method
R function call

### Endpoint
N/A (This is an R function, not a REST API endpoint)

### Parameters
#### Arguments
- **fig.grp** (dataframe) - Required - Dataframe with x, y values and associated curve for each pixel.
- **nr_neighbors** (numeric) - Optional - How many nearby neighbors to consider when guessing the value of missing pixels (default: 100).

### Request Example
```R
overlap_detect(fig.grp = your_dataframe, nr_neighbors = 20)
```

### Response
#### Success Response
- **res.df** (dataframe) - A dataframe with the detected x, y, group values for all curves.

#### Response Example
```R
# Example output structure (actual data will vary)
res.df <- data.frame(
  x = c(1, 2, 3, 4, 5),
  y = c(10, 12, 11, 13, 15),
  group = c("curve1", "curve1", "curve2", "curve2", "curve2")
)
```
```

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

### Detect Axis Ranges for Survival Curves (R)

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Detects the axis ranges (x and y) from an image of survival curves. This function is crucial for converting pixel coordinates to actual time and survival values. It takes parameters defining the image steps, start/end values, increments for both axes, and orientation of y-axis text.

```r
# Example with horizontal y-axis labels
range_list_horizontal <- range_detect(
  step1_fig = axes_result$step_1,
  step2_axes = axes_result$axes,
  x_start = 0,
  x_end = 60,
  x_increment = 5,
  y_start = 0,
  y_end = 100,
  y_increment = 10,
  y_text_vertical = FALSE
)

# Calculate actual value from pixel coordinate
pixel_y <- 250
actual_survival <- (pixel_y - range_list$Y_0pixel) * range_list$y_increment
```

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

### Resolve Overlapping Survival Curves - R

Source: https://context7.com/pechli-lab/survdigitizer/llms.txt

Detects and resolves overlapping regions between survival curves using k-nearest neighbors for similarity scoring. It processes grouped curve data and returns a dataframe with continuous curve paths, ensuring each point belongs to a single, resolved curve. The number of neighbors influences the accuracy and processing time.

```r
library(SurvdigitizeR)

# After color clustering
fig_grouped <- color_cluster(fig.df = fig_df, num_curves = 2, censoring = FALSE)

# Detect and resolve overlaps with default neighbors
fig_resolved <- overlap_detect(
  fig.grp = fig_grouped,
  nr_neighbors = 20
)

# Returns dataframe with continuous curve paths
head(fig_resolved)
#     x   y group
#   150 580     1
#   151 580     1
#   152 580     1
#   152 579     1
#   153 579     1

# Use more neighbors for better overlap resolution in complex curves
fig_resolved_precise <- overlap_detect(
  fig.grp = fig_grouped,
  nr_neighbors = 50
)

# Fewer neighbors for faster processing of simple curves
fig_resolved_fast <- overlap_detect(
  fig.grp = fig_grouped,
  nr_neighbors = 10
)

# Check for remaining gaps in curve
library(dplyr)
fig_resolved %>%
  group_by(group) %>%
  summarise(
    x_range = max(x) - min(x),
    y_range = max(y) - min(y),
    num_points = n()
  )

```

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

### Detect Overlap and Fill Gaps with overlap_detect (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/overlap_detect.html

The overlap_detect function identifies potential overlaps between digitized curves and fills in gaps using KNN similarity. It requires a dataframe with x, y coordinates and curve group information. The function returns a dataframe with the detected and gap-filled curve data.

```r
overlap_detect(fig.grp, nr_neighbors = 20)
```

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

### axes_identify

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/axes_identify.html

Identifies plot axes location within an image. It takes pixel data in HSL format and an optional background lightness threshold to segment the plot area.

```APIDOC
## axes_identify

### Description
Identifies plot axes location within an image. It takes pixel data in HSL format and an optional background lightness threshold to segment the plot area.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
#### Arguments
- **fig.hsl** (array of pixels in HSL format) - Description: Input pixel data in HSL format.
- **bg_lightness** (numeric) - Optional - Description: A lightness threshold value between 0 and 1. Pixels with lightness > bg_lightness are considered background and removed. Defaults to 0.1.

### Value
- **fig.hsl** (array of pixels) - The array of pixels cropped to the axes.
- **axes** (list) - A list containing `xaxis` and `yaxis` vectors of integers to index plot by columns and rows respectively.

### Example
```R
# axes_identify(fig.hsl = figure, bg_lightness = 0.1)
```
```

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

### Clean Image Pixels by Lightness and Text (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/fig_clean.html

The fig_clean function processes an array of pixels in HSL format to remove background colors close to white. It allows for an option to attempt Optical Character Recognition (OCR) to remove text elements from the plot, which is particularly useful for cleaning Kaplan-Meier curves or other scientific plots. The function requires HSL pixel data and returns a dataframe of the remaining pixel coordinates and their HSL values.

```r
fig_clean(fig.hsl, bg_lightness = 0.1, attempt_OCR = F, word_sensitivity = 30)
```

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

### Identify Plot Axes Location - R

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/axes_identify.html

The axes_identify function takes an array of pixels in HSL format and an optional background lightness threshold to identify and crop plot axes. It returns the cropped pixel data along with vectors indexing the plot by columns and rows.

```r
axes_identify(fig.hsl, bg_lightness = 0.1)
```

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

### Impute Overlapping Values with impute_overlap (R)

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/impute_overlap.html

This R function, impute_overlap, is designed to resolve overlapping color curves that can occur during the initial stages of a Kaplan-Meier (KM) study. It requires a dataframe containing 'x', 'y', and 'group' columns and an optional integer specifying the imputation interval size. The function returns a list of dataframes, one for each processed curve.

```r
impute_overlap(fig.curves = step4, size = 50)
```

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

### Isolate Final Singular Y Values for Curves - R

Source: https://github.com/pechli-lab/survdigitizer/blob/master/docs/reference/lines_isolate.html

The lines_isolate function in R takes a dataframe containing x, y, and group values for curves and returns a list of dataframes, where each dataframe contains the final singular y-values for a specific curve. This function can be a precursor to more advanced event detection.

```r
lines_isolate(fig.curves)
```