grannot_help.md

# GrAnnoT usage

To run GrAnnoT, your command line must look like this : ```grannot graph.gfa annotation.gff source_genome [options]```

### Positionnal arguments

GrAnnoT has 3 positionnal arguments :
- A pangenome graph in GFA format.
- The annotation of a genome included in the graph in GFF/GTF format.
- The name of the annotated genome. 

The graph must have W or P lines with no overlap between the segments. If the graph has P-lines, the names of the paths must look like this : ```IRGSP#0#Chr1```, with three fields being the genome name, the haplotype, and the chromosome/contig name.\
The name of the annotated genome must be in the second second field of the W line, or in the first part of the second field of the P line (see [GFA format specification](https://gfa-spec.github.io/GFA-spec/GFA1.html)).

If the annotation file refers to a specify haplotype of your source genome, use the option ```-sh``` or ```--source_haplotype``` to specify the name of the haplotype to consider as source of the annotation. This option requires the option ```-ht``` or ```--haplotype```.

### Graph annotation transfer

To transfer annotations on the graph, you have 2 options :
- ```-gff``` or ```--graph_gff``` : outputs the annotation of the graph on GFF format. Not recommended.
- ```-gaf``` or ```--graph_gaf``` : outputs the annotation of the graph in [GAF](https://github.com/lh3/gfatools/blob/master/doc/rGFA.md#the-graph-alignment-format-gaf) format.

### Genome annotation transfer

To transfer annotations on the choosen genomes, you must use the option
```-ann``` or ```--annotation```.

To choose where the annotations will be transfered, use these options:
- ```-t``` or ```--target``` : this option can take several arguments if you want to transfer on several genomes. If the option is not specified, GrAnnoT will transfer the annotation on all the genomes in the graph.
- ```-ht``` or ```--haplotype``` : by default GrAnnoT doesn't look at the haplotype field in the walks or paths. With this option the annotation will be transfered separately on the different haplotypes of the target genomes.


Additionnal files that give informations about the transfer can be obtained with these options :
- ```-aln``` or ```--alignment``` : outputs the alignments of the annotated features in the source genome and in a target genome.
- ```-var``` or ```--variation``` : outputs the detail of the variations between the features in the source genome and in the target genome.
- ```-pav``` or ```--pav_matrix``` : outputs a presence-absence variation matrix to recapitulate the annotation transfers. Requires the option  ```-ann/--annotation```. 
<!-- could change the -pav requirements to one among ann,var,aln, or no requirement-->

You can filter the annotations you transfer with these options :
- ```-cov``` or ```--coverage``` : specify the minimum requested coverage percentage between the original feature and the feature found in the target genome. Default is 80.
- ```-id``` or ```--identity``` : specify the minimum requested sequence identity percentage between the original feature and the feature found in the target genome. Default is 80.


### General options

- ```-coord``` or ```--segment_coordinates_path``` : specify the path of the directory ```seg_coord/``` made by GrAnnoT in a previous run. Use this only if you run GrAnnoT multiple times on the same graph for the same genomes. This directory must contain bed files for all the walks or paths of the genomes you need (source and target), and the files ```segments.txt``` and ```walks.txt```. If not specified GrAnnoT will recreate these files.
- ```-o``` or ```--outdir``` : stores all the output files in the given directory. By default they will be stored in the current directory.
- ```-v``` or ```--verbose``` : makes GrAnnoT more verbose.
- ```-V``` or ```--version``` : displays GrAnnoT version and exits.
- ```-h``` or ```--help``` : displays a help message and exits.