---
title: "Introduction to ggplotcli"
author: "Claas Heuer"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction to ggplotcli}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
  
```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Introduction

The `ggplotcli()` function converts any ggplot2 plot to a terminal-based visualization using Unicode Braille characters and ANSI colors.

## Basic Usage

```{r}
library(plotcli)
library(ggplot2)

# Create a ggplot with points and smooth line
mtcars_ggplot <- ggplot(mtcars, aes(x = mpg, y = wt)) +  
  geom_point() +  
  geom_smooth(method = "lm", color = "red") +
  labs(title = "Mtcars Dataset with Regression Line",  
       x = "Miles per Gallon",  
       y = "Weight")  

# Render in terminal
suppressMessages(ggplotcli(mtcars_ggplot, width = 60, height = 15))
```

## Color Aesthetics

ggplotcli supports color grouping just like ggplot2:

```{r}
# Colored by group
p <- ggplot(mtcars, aes(x = wt, y = mpg, color = factor(cyl))) +
  geom_point() +
  labs(title = "MPG vs Weight by Cylinders",
       color = "Cylinders")

ggplotcli(p, width = 60, height = 14)
```

```{r}
# Iris dataset with species colors
p <- ggplot(iris, aes(x = Sepal.Length, y = Sepal.Width, color = Species)) +
  geom_point() +
  labs(title = "Iris: Sepal Dimensions by Species")

ggplotcli(p, width = 60, height = 12)
```

## Density Plots with Colors

```{r}
p <- ggplot(mtcars, aes(x = mpg, color = factor(cyl))) +
  geom_density() +
  labs(title = "MPG Density by Cylinders")

ggplotcli(p, width = 60, height = 12)
```

## Faceting

### facet_wrap

Split plots by a categorical variable:

```{r}
p <- ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point(color = "blue") +
  facet_wrap(~cyl) +
  labs(title = "MPG vs Weight by Cylinders")

ggplotcli(p, width = 70, height = 14)
```

### facet_grid

Create a grid of plots by two variables:
 
```{r}
p <- ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point(color = "green") +
  facet_grid(am ~ cyl) +
  labs(title = "MPG: Transmission (rows) x Cylinders (cols)")

ggplotcli(p, width = 70, height = 18)
```

## Combining Multiple Geoms

```{r}
# Histogram with density overlay
p <- ggplot(mtcars, aes(x = mpg)) +
  geom_histogram(aes(y = after_stat(density)), bins = 10, fill = "gray") +
  geom_density(color = "red") +
  labs(title = "Histogram with Density Overlay")

ggplotcli(p, width = 60, height = 12)
```

## Canvas Types

Three rendering modes are available:

```{r}
p <- ggplot(mtcars, aes(x = wt, y = mpg)) + 
  geom_point(color = "blue")

# High resolution with Braille (default)
ggplotcli(p + labs(title = "Braille Canvas (default)"), 
          width = 50, height = 10, canvas_type = "braille")

# Block characters (medium resolution)
ggplotcli(p + labs(title = "Block Canvas"), 
          width = 50, height = 10, canvas_type = "block")

# ASCII for maximum compatibility
ggplotcli(p + labs(title = "ASCII Canvas"), 
          width = 50, height = 10, canvas_type = "ascii")
```

## Styling Options

```{r}
p <- ggplot(mtcars, aes(x = hp, y = qsec)) +
  geom_point(color = "cyan") +
  labs(title = "With Border and Grid")

# Add border and grid
ggplotcli(p, width = 55, height = 10, border = TRUE, grid = "major")
```

## Theme Auto-Detection

ggplotcli automatically respects ggplot2 themes:

```{r}
p <- ggplot(mtcars, aes(x = wt, y = mpg)) +
  geom_point(color = "magenta")

# theme_bw adds grid and border
ggplotcli(p + theme_bw() + labs(title = "theme_bw() - Grid + Border"), 
          width = 55, height = 10, border = "auto", grid = "auto")

# theme_classic has border but no grid
ggplotcli(p + theme_classic() + labs(title = "theme_classic() - Border Only"), 
          width = 55, height = 10, border = "auto", grid = "auto")
```

## Learn More

See the full vignette "ggplotcli: Universal ggplot2 to Terminal Plotting" for more examples including all supported geoms, advanced styling, and more.