---
title: "Getting Started with artma"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with artma}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

**artma** (Automatic Replication Tools for Meta-Analysis) is an R package designed to make meta-analysis accessible, reproducible, and comprehensive. This vignette will get you up and running quickly, showing you how to use artma for your meta-analysis needs.

## Quick Start: Your First Analysis

The simplest way to use artma is to call the main function:

```r
library(artma)
results <- artma()
```

When you run this in an interactive R session, artma will:

1. **Guide you through creating an options file** - This stores all your analysis settings
2. **Help you load your data** - You'll specify where your dataset is located
3. **Map your columns** - artma will recognize common column names or let you specify them
4. **Let you choose methods** - Select which analyses you want to run
5. **Run your analysis** - Execute everything and return results

If you want artma to open the results folder for you at the end of a run, set `open_results = TRUE`. You can always access your results later manually using `artma::results.open()`.

That's it! The function handles all the complexity behind the scenes.

## Understanding the Core Concepts

Before diving deeper, it helps to understand three key concepts:

### 1. The `artma()` Function

`artma()` is the main entry point for the package. It orchestrates everything:

- **Loading configuration** from options files
- **Preparing your data** (reading, cleaning, validating)
- **Running analytical methods** (funnel plots, Bayesian analysis, etc.)
- **Returning results** in a structured format

You can use it in different ways:

```r
# Fully interactive - prompts for everything
artma()

# Specify methods to run
artma(methods = c("funnel_plot", "bma"))

# Use a specific options file
artma(options = "my_analysis.yaml")

# Provide data directly (bypasses file reading)
artma(data = my_dataframe, methods = "effect_summary_stats")
```

### 2. Options Files

Options files are YAML configuration files that store all your analysis settings. Think of them as recipes for your meta-analysis:

- **Data location** - Where your dataset is stored
- **Column mappings** - Which columns contain effect sizes, standard errors, etc.
- **Method parameters** - Settings for each analysis method
- **Output preferences** - How you want results formatted

The key benefit: **reproducibility**. Save your options file, and you can rerun the exact same analysis anytime.

### 3. Methods

Methods are the analytical functions that perform specific meta-analysis tasks. Each method does something different:

- `effect_summary_stats` - Calculate overall effect sizes and confidence intervals
- `funnel_plot` - Visualize publication bias
- `bma` - Bayesian Model Averaging
- `linear_tests` - Test linear relationships
- `nonlinear_tests` - Test nonlinear relationships
- `exogeneity_tests` - Test for endogeneity
- `p_hacking_tests` - Detect p-hacking patterns
- `variable_summary_stats` - Summary statistics for variables

You can run one method, multiple methods, or all methods in a single call.

## Common Workflows

### Workflow 1: Interactive Analysis (Recommended for Beginners)

This is the easiest way to get started:

```r
# Step 1: Load the package
library(artma)

# Step 2: Run interactively
results <- artma()

# Step 3: Explore results
names(results)  # See which methods ran
results$effect_summary_stats  # Access specific results
```

During the interactive session, you'll be guided through:

- Creating or selecting an options file
- Specifying your data file path
- Mapping column names (artma tries to auto-detect these)
- Choosing which methods to run

### Workflow 2: Using an Existing Options File

Once you've created an options file, reuse it:

```r
# Run with a specific options file
results <- artma(options = "my_analysis.yaml")

# Or specify the directory too
results <- artma(
  options = "my_analysis.yaml",
  options_dir = "~/my_meta_analyses/configs"
)
```

This is perfect when:

- You're rerunning a previous analysis
- You want to share your analysis configuration
- You're doing sensitivity analyses with different parameters

### Workflow 3: Programmatic Analysis

For scripts and automation:

```r
# Create options file programmatically
artma::options.create(
  options_file_name = "analysis_2025",
  user_input = list(
    "data.source_path" = "/path/to/data.csv",
    "data.colnames.effect" = "effect_size",
    "data.colnames.se" = "standard_error",
    "methods.effect_summary_stats.conf_level" = 0.95
  )
)

# Run analysis
results <- artma(
  options = "analysis_2025",
  methods = c("effect_summary_stats", "funnel_plot")
)
```

### Workflow 4: Using Data Already in R

If your data is already loaded in R:

```r
# Your data frame
my_data <- data.frame(
  effect = c(0.5, 0.3, 0.7, 0.4),
  se = c(0.1, 0.15, 0.12, 0.11),
  study = c("Study A", "Study B", "Study C", "Study D"),
  n_obs = c(100, 150, 120, 130)
)

# Run analysis directly
results <- artma(
  data = my_data,
  methods = "effect_summary_stats"
)
```

Note: When you provide data directly, you still need options for method parameters, but artma will handle data reading automatically.

## Understanding Results

The `artma()` function returns a named list, where each element corresponds to a method that was run:

```r
results <- artma(methods = c("effect_summary_stats", "funnel_plot"))

# Structure:
# results
# ├── effect_summary_stats  (results from effect summary statistics)
# └── funnel_plot           (results from funnel plot analysis)
```

The structure of each result depends on the method. Some methods return:

- Summary statistics (tables, means, confidence intervals)
- Test results (p-values, test statistics)
- Visualizations (plots, graphs)
- Model objects (for further analysis)

To explore results:

```r
# See what methods ran
names(results)

# Access a specific result
effect_results <- results$effect_summary_stats

# The structure varies by method - use str() to explore
str(effect_results)
```

## Choosing Methods

### Discovering Available Methods

To see what methods are available:

```r
artma::methods.list()
```

This prints all available methods to the console.

### Selecting Methods

You have several options:

```r
# Run specific methods
artma(methods = c("effect_summary_stats", "bma"))

# Run all methods
artma(methods = "all")

# Interactive selection (if methods not specified)
artma()  # Will prompt you to choose
```

### Method Execution Order

Methods run in a predefined order (you don't need to worry about this, but it's good to know). If you specify multiple methods, they'll execute in the optimal sequence automatically.

## Working with Options Files

### Creating Options Files

Options files are created automatically when needed, but you can also create them explicitly:

```r
# Interactive creation
artma::options.create()

# Programmatic creation
artma::options.create(
  options_file_name = "my_analysis",
  user_input = list(
    "data.source_path" = "/path/to/data.csv",
    "data.colnames.effect" = "effect_size",
    "data.colnames.se" = "standard_error"
  )
)
```

### Managing Options Files

```r
# List all options files
artma::options.list()

# Copy an options file
artma::options.copy(
  options_file_name_from = "baseline.yaml",
  options_file_name_to = "sensitivity.yaml"
)

# Modify an options file
artma::options.modify(
  options_file_name = "my_analysis.yaml",
  options_to_modify = list(
    "methods.effect_summary_stats.conf_level" = 0.99
  )
)

# Validate an options file
artma::options.validate("my_analysis.yaml")
```

For detailed information about options files, see the [Understanding Options Files](options-files.html) vignette.

## Data Requirements

### Required Columns

Your dataset needs certain columns for artma to work. The minimum required columns are:

- **Effect size** - The effect you're analyzing (e.g., correlation, mean difference)
- **Standard error** - The uncertainty in the effect size
- **Study identifier** - A unique identifier for each study/observation

### Column Mapping

artma uses flexible column mapping. Your columns don't need specific names - you just need to tell artma which column contains what. For example:

- Your effect column might be called `beta`, `effect_size`, `r`, or `d`
- Your standard error column might be called `se`, `standard_error`, or `se_beta`
- Your study column might be called `study`, `paper_id`, or `observation`

artma tries to auto-detect these mappings, but you can always specify them manually.

### Supported Data Formats

artma can read data from:

- CSV files (`.csv`)
- Excel files (`.xlsx`, `.xls`)
- JSON files (`.json`)
- Stata files (`.dta`)
- R data files (`.rds`)

### Data Preprocessing

artma automatically handles:

- Missing value detection and treatment
- Data type conversion
- Column standardization
- Outlier detection (with optional winsorization)

You control these behaviors through your options file.

## Tips for Success

### 1. Start Simple

Begin with a single method to understand the workflow:

```r
results <- artma(methods = "effect_summary_stats")
```

Once comfortable, add more methods.

### 2. Use Descriptive Options File Names

Name your options files clearly:

- `charity_effects_2025.yaml` - Better than `config1.yaml`
- `sensitivity_analysis.yaml` - Better than `test.yaml`

### 3. Save Your Options Files

Options files are your analysis recipes. Save them with your project for reproducibility.

### 4. Check Verbosity

Control how much information artma displays:

```r
# In your options file or via options()
options(artma.verbose = 3)  # Default: informative
options(artma.verbose = 1)  # Minimal: errors only
options(artma.verbose = 4)  # Verbose: everything
```

### 5. Validate Before Running

If you're modifying options files manually, validate them:

```r
artma::options.validate("my_analysis.yaml")
```

This catches errors before you run the analysis.

## Getting Help

### Documentation

- `?artma` - Main function help
- `?artma::methods.list` - List available methods
- `?artma::options.create` - Create options files
- Vignettes - Detailed guides (like this one!)

### Verbosity Levels

If something isn't working, increase verbosity:

```r
options(artma.verbose = 4)  # Maximum detail
results <- artma()
```

This shows everything artma is doing, which helps diagnose issues.

### Validation

When in doubt, validate:

```r
# Validate options file
artma::options.validate("my_analysis.yaml")

# Check available methods
artma::methods.list()

# Check data structure (after loading)
df <- artma::prepare_data()
str(df)
```

## Next Steps

Once you're comfortable with the basics, read the options vignette for deeper configuration
and try a few methods on your own data.