---
title: "Using the Text Annotation Interface"
author: "Chao Liu"
date: "`r Sys.Date()`"
output: 
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 3
vignette: >
  %\VignetteIndexEntry{Using the Text Annotation Interface}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5,
  fig.align = 'center',
  fig.path = "/man/figures/"
)
library(textAnnotatoR)
```

# Introduction

The Text Annotation Interface provides a comprehensive environment for qualitative data analysis through text annotation. This vignette will guide you through using the interface effectively, from basic text annotation to advanced features like code hierarchies and comparative analysis.

# Getting Started

## Launching the Interface

To start using the text annotation interface, simply call the `annotate_gui()` function:

```{r eval=FALSE}
library(textAnnotatoR)
annotate_gui()
```

This will open the Shiny application in your default web browser. The interface is divided into several tabs, each offering different functionality for your annotation work.

```{r, echo=FALSE, out.width="100%", fig.cap="Main Interface Overview"}
knitr::include_graphics("../man/figures/interface_overview.png")
```

## Interface Overview

The interface consists of:

1. A top toolbar with project management buttons
2. A main content area with multiple tabs
3. Side margins with quick-access tools
4. A text display area showing your document

# Basic Operations

## Project Management {#project-management}

### Creating a New Project

1. Click the "New Project" button in the top toolbar
2. If you have unsaved changes, you'll be prompted to save them
3. Confirm creation of the new project

```{r, echo=FALSE, out.width="80%", fig.cap="New Project Dialog"}
knitr::include_graphics("../man/figures/new_project.png")
```

### Saving Projects

1. Click "Save Project"
2. Enter a project name
3. Choose a save location
4. Click "Save" to confirm

### Loading Projects

1. Click "Load Project"
2. Navigate to your project file
3. Select the file and click "Load"

## Text Import and Management {#text-import}

### Importing Text

1. Go to the "File" tab
2. Click "Choose File" to select your text document
3. Supported formats include:
   - .txt files
   - .docx files
   - .pdf files
4. Click "Import Text" to load the content

```{r, echo=FALSE, out.width="80%", fig.cap="File Import Interface"}
knitr::include_graphics("../man/figures/file_import.png")
```

## Basic Annotation {#basic-annotation}

### Selecting Text

1. Click the selection tool (cursor icon) in the right margin
2. Click and drag across the text you want to annotate
3. The selected text will be highlighted in yellow

### Applying Codes

```{r eval=FALSE}
# Example of code application via the API (if available)
annotate_text(selected_text, code = "important_theme")
```

1. With text selected, you can:
   - Enter a new code in the "Code" field
   - Select an existing code from the dropdown
2. Click "Apply Code" to annotate the selection
3. The coded text will be highlighted with a unique color

### Adding Memos

1. Select text to annotate
2. Enter your memo in the "Memo" text area
3. Click "Save" to attach the memo to the selection

# Advanced Features

## Code Management {#code-management}

### Code Hierarchy

The "Themes" tab allows you to organize your codes hierarchically:

```{r eval=FALSE}
# Example of code hierarchy structure
codes <- list(
  "Methods" = c("Qualitative", "Quantitative"),
  "Results" = c("Findings", "Discussion")
)
```

1. Click "Add Theme" to create a new theme
2. Use "Add Code to Theme" to organize existing codes
3. The hierarchy is displayed in a tree structure

### Merging Codes

```{r eval=FALSE}
# Example of code merging logic
merge_codes(c("code1", "code2"), new_code = "merged_code")
```

1. Click "Merge Codes" button
2. Select the codes you want to merge
3. Enter a name for the new merged code
4. Confirm the merge

## Analysis Tools {#analysis-tools}

### Code Frequency Analysis

```{r eval=FALSE}
# Example of frequency analysis
analyze_code_frequency(annotations)
```

1. Click "Code Frequency" in the Analysis tab
2. View the bar chart showing code usage frequency
3. Export results if needed

### Code Co-occurrence Analysis

1. Click "Code Co-occurrence"
2. Examine the relationship between codes through:
   - Network visualization
   - Heatmap view
   - Statistical summary

```{r, echo=FALSE, out.width="90%", fig.cap="Code Co-occurrence Analysis"}
knitr::include_graphics("../man/figures/co_occurrence.png")
```

### Text Summary

Generate basic statistics about your text and annotations:
```{r eval=FALSE}
# Example of summary statistics
summary_stats <- analyze_text(text, annotations)
print(summary_stats)
```

## Comparison Tools {#comparison-tools}

The comparison tab allows you to analyze coding patterns between different coders:

1. Upload two sets of annotations
2. Select analysis metrics
3. View comparisons through:
   - Distribution plots
   - Overlap analysis
   - Sequence patterns

# Exporting Data {#exporting}

## Saving Annotations

```{r eval=FALSE}
# Example of saving annotations
save_annotations(annotations, "output.csv")
```

1. Go to the "Records" tab
2. Click "Save Records"
3. Choose format:
   - CSV
   - JSON
4. Select save location

## Exporting Annotated Text

1. Click "Save Annotated Text"
2. Choose format:
   - HTML (maintains formatting and colors)
   - Text (includes code markers)
3. Select save location

# Best Practices {#best-practices}

## Organizing Your Work

1. Create meaningful code names
2. Use themes to group related codes
3. Add descriptive memos
4. Save your work frequently

## Efficient Coding

1. Use the selection tool for precise text selection
2. Utilize keyboard shortcuts when available
3. Organize codes hierarchically as patterns emerge
4. Review and merge similar codes periodically

## Quality Control

1. Regularly review your coding scheme
2. Use the comparison tools to check coding consistency
3. Export and backup your work frequently
4. Document your coding decisions in memos

# Troubleshooting {#troubleshooting}

## Common Issues

### Text Import Problems

- Ensure your text file is in a supported format
- Check for encoding issues
- Try breaking large files into smaller segments

### Saving Issues

- Verify you have write permissions
- Check available disk space
- Use relative paths when possible

### Display Problems

- Clear your browser cache
- Try a different browser
- Check for browser compatibility

# Conclusion

The Text Annotation Interface provides a robust environment for qualitative data analysis. By following this guide and exploring the various features, you can develop an efficient workflow for your annotation projects. Remember to:

- Save your work regularly
- Organize your codes effectively
- Use the analysis tools to gain insights
- Follow best practices for consistent results

---

*Note: This vignette reflects the current version of the Text Annotation Interface. Features may be updated or changed in future versions.*