[![](https://img.shields.io/badge/download%20html-blue)](../rendered-html/r-markdown-basics.html)
[![](https://img.shields.io/badge/download%20Rmd-blue)](r-markdown-basics.Rmd)

```{r setup, include=FALSE}
# Set global options for all code chunks in this document
# echo = TRUE means code will be displayed along with its output
knitr::opts_chunk$set(echo = TRUE)
```

## Welcome to R Markdown!

R Markdown is a powerful tool that combines the simplicity of Markdown with the computational power of R. It enables you to:

🎯 **Key Benefits**:
- Create **reproducible** documents that combine narrative text and code
- Generate **professional reports** in multiple formats (HTML, PDF, Word)
- Build **interactive dashboards** and presentations
- Share your work with both technical and non-technical audiences

Perfect for:
- 📊 Data Analysis Reports
- 📚 Technical Documentation
- 🎓 Academic Papers
- 📑 Presentations
- 🔍 Exploratory Data Analysis

## Part 1: Basic Structure

An R Markdown document consists of three essential components, each serving a specific purpose:

### 1. YAML Header
The YAML header controls document-wide settings and output format:

```yaml
---
title: "My First R Markdown"    # Document title
author: "Your Name"             # Author name
date: "2024-03-20"             # Publication date
output: html_document          # Output format (html, pdf, word)
---
```

**Key YAML Options**:
- `title`: Main document heading
- `author`: Document creator
- `date`: Publication date (can use "`r Sys.Date()`" for automatic dating)
- `output`: Desired output format

### 2. Text Content
Markdown syntax provides easy-to-use formatting:

# Level 1 Heading (Largest)
## Level 2 Heading
### Level 3 Heading (Smaller)

**Text Formatting**:
- *Italics*: Surround text with single asterisks (`*text*`)
- **Bold**: Use double asterisks (`**text**`)
- `Code`: Use backticks for inline code (`` `code` ``)
- [Links](https://www.r-project.org/): Create with `[text](url)`

**Lists**:
- Unordered lists use hyphens (-)
  * Sub-items use indentation
    + Can use different markers
- Continue main list

1. Ordered lists use numbers
2. Numbers auto-increment
3. Can mix with unordered lists
   - Like this
   - And this

### 3. Code Chunks
Code chunks are where R code lives and executes:

```{r example-chunk}
# Create a simple vector and calculate statistics
x <- 1:10                  # Generate sequence 1 to 10
mean(x)                    # Calculate mean
sd(x)                     # Calculate standard deviation
summary(x)                # Generate summary statistics
```

## Part 2: Code Chunks in Detail

### Creating Code Chunks

Three methods to insert code chunks:

1. 🖱️ **GUI Method**: 
   - Click "Insert" in RStudio
   - Select "R" for R code chunks

2. ⌨️ **Keyboard Shortcut**:
   - Mac: `Cmd + Option + I`
   - Windows/Linux: `Ctrl + Alt + I`

3. ✍️ **Manual Method**:
   - Type: \```{r chunk-name}
   - End with: \```

### Chunk Options

Control chunk behavior with options:

```{r options-demo, echo=TRUE, message=FALSE, warning=FALSE, fig.width=8, fig.height=6}
# Load required packages
library(tidyverse)

# Create an example plot
ggplot(mtcars, aes(x = mpg, y = wt, color = factor(cyl))) +
  geom_point(size = 3) +                          # Add points
  labs(title = "Car Weight vs MPG",               # Add labels
       x = "Miles Per Gallon",
       y = "Weight (1000 lbs)",
       color = "Cylinders") +
  theme_minimal()                                 # Use minimal theme
```

**Essential Chunk Options**:
- `echo`: Show/hide code (TRUE/FALSE)
- `eval`: Execute code (TRUE/FALSE)
- `message`: Display messages (TRUE/FALSE)
- `warning`: Show warnings (TRUE/FALSE)
- `fig.width/fig.height`: Set plot dimensions
- `fig.cap`: Add figure caption
- `include`: Include chunk output (TRUE/FALSE)

## Part 3: Best Practices

### 1. Document Organization

📝 **Structure Guidelines**:

✅ **Recommended**:
- Begin with clear introduction
- Use logical heading hierarchy
- Include navigation aids (TOC)
- End with summary/conclusions
- Keep sections focused

❌ **Avoid**:
- Skipping heading levels
- Writing walls of text
- Leaving code unexplained
- Mixed formatting styles

### 2. Code Chunk Management

🔧 **Code Organization**:

✅ **Best Practices**:
```{r load-packages}
# Load all required packages at start
library(tidyverse)      # For data manipulation and visualization
library(knitr)         # For nice tables
```

```{r data-preparation}
# Prepare data for analysis
data <- mtcars %>%
  select(mpg, wt, cyl) %>%     # Select relevant columns
  filter(mpg > 20) %>%         # Filter for high MPG
  mutate(                      # Create new variables
    efficiency = mpg/wt,
    cyl = factor(cyl)
  )
```

### 3. Text Formatting

📚 **Writing Guidelines**:

✅ **Do**:
- Use consistent formatting
- Break text into paragraphs
- Include descriptive lists
- Add relevant references

❌ **Don't**:
- Mix formatting styles
- Write dense paragraphs
- Leave terms undefined
- Skip documentation

### 4. Output Management

🎨 **Presentation Tips**:

```{r plot-customization, fig.width=10, fig.height=6, fig.cap="Detailed Analysis of MPG vs Weight"}
# Create a professional visualization
ggplot(mtcars, aes(x = mpg, y = wt, color = factor(cyl))) +
  geom_point(size = 3, alpha = 0.7) +            # Add points with transparency
  geom_smooth(method = "lm", se = TRUE) +        # Add trend line with CI
  facet_wrap(~cyl, scales = "free") +            # Split by cylinders
  labs(
    title = "Car Weight vs MPG by Number of Cylinders",
    subtitle = "Analysis of Motor Trend Car Road Tests",
    x = "Miles Per Gallon (MPG)",
    y = "Weight (1000 lbs)",
    color = "Cylinders"
  ) +
  theme_minimal() +                              # Use minimal theme
  theme(
    legend.position = "bottom",                  # Move legend
    plot.title = element_text(size = 16),        # Customize text
    plot.subtitle = element_text(size = 12)
  )
```

## Part 4: Common Patterns

### Including Tables

```{r table-example}
# Create a formatted table
library(knitr)
mtcars %>%
  head() %>%                           # Take first 6 rows
  select(mpg, cyl, wt, hp) %>%        # Select key columns
  kable(
    caption = "Sample of Motor Trend Car Data",
    digits = 2,                        # Round numbers
    align = c('r', 'c', 'r', 'r')     # Align columns
  )
```

### Including Equations

R Markdown supports LaTeX equations:

**Inline Math**: $y = \beta_0 + \beta_1x + \epsilon$

**Display Math**:
$$
\text{MPG} = \beta_0 + \beta_1\text{Weight} + \beta_2\text{Cylinders} + \epsilon \\
\text{where } \epsilon \sim N(0, \sigma^2)
$$

### Including Images

External images can be included:

![RStudio Logo](https://www.rstudio.com/wp-content/uploads/2018/10/RStudio-Logo-Flat.png)

## Part 5: Troubleshooting Tips

🔍 **Common Issues and Solutions**:

1. **Knitting Errors**
   - ✓ Check package installation
   - ✓ Verify syntax in all chunks
   - ✓ Confirm file paths
   - ✓ Look for missing dependencies

2. **Figure Issues**
   - ✓ Adjust chunk options
   - ✓ Check plot specifications
   - ✓ Verify data integrity
   - ✓ Test device settings

3. **Code Problems**
   - ✓ Validate package versions
   - ✓ Ensure unique chunk names
   - ✓ Debug code separately
   - ✓ Check working directory

## Practice Exercises

🎯 **Hands-on Learning**:

1. **Basic Document** (15 mins)
   - Create new .Rmd file
   - Add YAML header
   - Include text sections
   - Insert code chunk

2. **Code Integration** (20 mins)
   - Load dataset
   - Create summary statistics
   - Generate basic plot
   - Add chunk options

3. **Advanced Features** (25 mins)
   - Include equations
   - Create custom table
   - Add figure caption
   - Use cross-references

## Next Steps

🚀 **Advanced Topics to Explore**:

1. **Output Formats**
   - PDF documents
   - Word reports
   - HTML slides
   - Dashboards

2. **Advanced Features**
   - Custom templates
   - CSS styling
   - Interactive plots
   - Cross-references

3. **Integration**
   - Version control
   - Collaboration
   - Automation
   - Publishing

## Additional Resources

📚 **Learning Materials**:

1. **Official Documentation**
   - [R Markdown Cheat Sheet](https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf)
   - [R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/)
   - [R Markdown Guide](https://bookdown.org/yihui/rmarkdown/)

2. **Online Learning**
   - [RStudio Tutorials](https://rmarkdown.rstudio.com/lesson-1.html)
   - [DataCamp Courses](https://www.datacamp.com/courses/reporting-with-r-markdown)
   - [Coursera R Programming](https://www.coursera.org/learn/r-programming)

3. **Community Resources**
   - [Stack Overflow - [r-markdown]](https://stackoverflow.com/questions/tagged/r-markdown)
   - [RStudio Community](https://community.rstudio.com/c/R-Markdown)
   - [#rstats on Twitter](https://twitter.com/hashtag/rstats) 