# Output
# Repeat Pipeline Output Guide

This guide describes all outputs generated by the Ensembl genes repeat annotation pipeline, including file formats, locations and interpretation.

## Table of Contents

1. Output Directory Structure
2. Module Outputs
3. File Formats
4. Cached Outputs
5. Version Tracking
6. Interpreting Results

---

# Output Directory Structure

## Standard Layout

```text
${params.outdir}/
├── ${meta.gca}/
│   ├── rm_library/                  # Downloaded RepeatModeler library
│   ├── repeatmasker/                # RepeatMasker results
│   ├── red/                         # RED repeat detection results
│   ├── repeat_statistics/           # Repeat annotation statistics
│   ├── reports/                     # Summary reports
│   └── versions.yml                 # Software versions
│
└── pipeline_info/
    ├── execution_report.html
    ├── execution_timeline.html
    └── execution_trace.txt
```

## Cache Directory Structure

```text
${params.cacheDir}/
├── ${meta.gca}/
│   ├── repeatmodeler/
│   ├── repeatmasker/
│   └── red/
│
└── repeat_libraries/
```

---

# Module Outputs

## CHECK_AND_DOWNLOAD_RMLIBRARY

**Published to:** `${params.outdir}/${meta.gca}/rm_library/`

### Files

* `${meta.gca}.repeatmodeler.fa`
* `versions.yml`

### Description

Downloads the RepeatModeler repeat library from the supplied URL after validating that the resource exists.

### Typical Output

```text
rm_library/
├── GCA_XXXXXXXXX.X.repeatmodeler.fa
└── versions.yml
```

---

## CHECK_AND_DOWNLOAD_DFAM

**Published to:** `${params.outdir}/${meta.gca}/dfam/`

### Files

* Dfam repeat library
* `versions.yml`

### Description

Downloads and prepares the selected Dfam repeat library for downstream annotation.

---

## RUN_REPEATMASKER

**Published to:** `${params.outdir}/${meta.gca}/repeatmasker/`

### Typical Files

* Masked genome FASTA
* `.out`
* `.tbl`
* `.cat.gz`
* Annotation files
* `versions.yml`

### Description

Runs RepeatMasker using the configured repeat library and produces masked genome sequences together with detailed repeat annotations.

---

## RUN_RED

**Published to:** `${params.outdir}/${meta.gca}/red/`

### Typical Files

* Repeat coordinates
* Soft-masked genome
* Summary statistics
* `versions.yml`

### Description

Detects repetitive regions using RED without relying on a predefined repeat library.

---

## Repeat Statistics

**Published to:** `${params.outdir}/${meta.gca}/repeat_statistics/`

### Typical Outputs

* Repeat counts
* Repeat coverage
* Repeat class summaries
* Summary reports

These statistics summarise the repeat content identified across the genome assembly.

---

# File Formats

## FASTA

Used for:

* RepeatModeler libraries
* Masked genome assemblies

---

## GFF/BED

Used for genomic repeat coordinates.

Typical fields include:

* sequence
* start
* end
* strand
* repeat class
* repeat family

---

## RepeatMasker Output

Typical files include:

* `.out`
* `.tbl`
* `.cat.gz`

These contain the detailed RepeatMasker annotation and summary statistics.

---

## YAML

Every module generates a `versions.yml` file describing the software versions used during execution.

Example:

```yaml
CHECK_AND_DOWNLOAD_RMLIBRARY:
  wget: 1.24

RUN_REPEATMASKER:
  RepeatMasker: 4.1.x

RUN_RED:
  RED: 2.x
```

---

# Cached Outputs

The pipeline caches expensive resources whenever possible.

Examples include:

* downloaded RepeatModeler libraries
* downloaded Dfam libraries
* RepeatMasker intermediate files
* RED intermediate files

Caching avoids repeated downloads and unnecessary recomputation.

---

# Version Tracking

Every module generates a `versions.yml` file recording the versions of the software used during execution.

Typical tools include:

* RepeatMasker
* RepeatModeler
* RED
* wget
* Perl
* Python

These files support reproducibility and troubleshooting.

---

# Interpreting Results

## RepeatMasker

The RepeatMasker output provides:

* repeat family assignments
* repeat class assignments
* genomic coordinates
* percentage divergence from the consensus sequence

Higher repeat coverage generally indicates a more repetitive genome.

---

## RED

RED identifies repetitive regions independently of known repeat libraries.

Comparing RED and RepeatMasker results can help identify:

* novel repeat content
* lineage-specific repeats
* gaps in curated repeat libraries

---

## Output Checklist

After pipeline completion verify that:

* RepeatModeler libraries were downloaded successfully.
* RepeatMasker completed without errors.
* RED completed successfully.
* Repeat statistics were generated.
* All expected output directories are present.
* `versions.yml` files exist.
* Pipeline execution reports were produced.

---

## Quick Reference

| Module                       | Primary Output         | Location                                          |
| ---------------------------- | ---------------------- | ------------------------------------------------- |
| CHECK_AND_DOWNLOAD_RMLIBRARY | RepeatModeler library  | `${params.outdir}/${meta.gca}/rm_library/`        |
| CHECK_AND_DOWNLOAD_DFAM      | Dfam library           | `${params.outdir}/${meta.gca}/dfam/`              |
| RUN_REPEATMASKER             | Repeat annotations     | `${params.outdir}/${meta.gca}/repeatmasker/`      |
| RUN_RED                      | RED repeat annotations | `${params.outdir}/${meta.gca}/red/`               |
| Repeat Statistics            | Summary reports        | `${params.outdir}/${meta.gca}/repeat_statistics/` |
| All modules                  | `versions.yml`         | `${params.outdir}/${meta.gca}/`                   |

---

## Next Steps

* [Parameters Reference](parameters.md)
* [Input Documentation](input.md)
* [Module Documentation](modules/index.md)
* [Workflow Documentation](workflows/index.md)