Merge pull request #111 from griffithlab/doc_associate

strand, associate

docs/commands/cis-splice-effects-associate.md

@@ -0,0 +1,38 @@
+[csei]: ../images/csei_examples.png
+
+###Synopsis
+The `cis-splice-effects associate` command is used to identify splicing misregulation events. This command is similar to `cis-splice-effects identify`, but takes the BED output of `junctions extract` in lieu of a BAM file with RNA alignments. The tool then proceeds to associate non-canonical splicing junctions near the variant sites.
+
+###Usage
+`regtools cis-splice-effects associate [options] variants.vcf junctions.bed ref.fa annotations.gtf`
+
+###Input
+| Input                  | Description |
+| ------                 | ----------- |
+| variants.vcf | Variant call in VCF format from which to look for cis-splice-effects.|
+| junctions.bed | BED file of junctions to look through for evidence of splice events. The file is expected to be in the [BED12 format](junctions-extract.md#output) of the `junctions extract` output. |
+| ref.fa          | The reference FASTA file. The donor and acceptor sequences used in the "splice-site" column of the annotated junctions are extracted from the FASTA file. |
+| annotations.gtf | The GTF file specifies the transcriptome that is used to annotate the junctions and variants. For examples, the Ensembl GTFs for release78 are [here](ftp://ftp.ensembl.org/pub/release-78/gtf/).|
+
+**Note** - Please make sure that the version of the annotation GTF that you use corresponds with the version of the assembly build (ref.fa) and that the co-ordinates in the VCF file are also from the same build.
+
+###Options
+| Option  | Description |
+| ------  | ----------- |
+| -o STR	|	Output file containing the aberrant splice junctions with annotations. [STDOUT]	|
+| -v STR	|	Output file containing variants annotated as splice relevant (VCF format).	|
+| -j STR	|	Output file containing the aberrant junctions in BED12 format.	|
+| -s INT	|	Strand specificity of RNA library preparation, where 0 = unstranded/XS, 1 = first-strand/RF, 2 = second-strand/FR. This option is required. If your alignments contain XS tags, these will be used in the "unstranded" mode. |
+| -w INT	|	Window size in b.p to associate splicing events in. The tool identifies events in variant.start +/- w basepairs. Default behaviour is to look at the window between previous and next exons.	|
+| -e INT	|	Maximum distance from the start/end of an exon to annotate a variant as relevant to splicing, the variant is in exonic space, i.e a coding variant. [3]	|
+| -i INT	|	Maximum distance from the start/end of an exon to annotate a variant as relevant to splicing, the variant is in intronic space. [2]	|
+| -I	|	Annotate variants in intronic space within a transcript(not to be used with -i).	|
+| -E	|	Annotate variants in exonic space within a transcript(not to be used with -e).	|
+| -S	|	Don't skip single exon transcripts.	|
+
+###Output
+For an explanation of the annotated junctions that are identified by this command please refer to the output of the `junctions annotate` command [here](junctions-annotate.md#output)
+For an explanation of the annotated variants that are identified by this command when using the -v option, please refer to the output of the `variants annotate` command [here](variants-annotate.md#output)
+
+###Examples
+![cis-splice-effects identify example][csei]

docs/commands/cis-splice-effects-identify.md

@@ -22,7 +22,7 @@ The `cis-splice-effects identify` command is used to identify splicing misregula
 | -o STR	|	Output file containing the aberrant splice junctions with annotations. [STDOUT]	|
 | -v STR	|	Output file containing variants annotated as splice relevant (VCF format).	|
 | -j STR	|	Output file containing the aberrant junctions in BED12 format.	|
-| -s INT	|	Strand specificity of RNA library preparation (0 = unstranded, 1 = first-strand/RF, 2, = second-strand/FR). [1]	|
+| -s INT	|	Strand specificity of RNA library preparation, where 0 = unstranded/XS, 1 = first-strand/RF, 2 = second-strand/FR. This option is required. If your alignments contain XS tags, these will be used in the "unstranded" mode. |
 | -w INT	|	Window size in b.p to identify splicing events in. The tool identifies events in variant.start +/- w basepairs. Default behaviour is to look at the window between previous and next exons.	|
 | -e INT	|	Maximum distance from the start/end of an exon to annotate a variant as relevant to splicing, the variant is in exonic space, i.e a coding variant. [3]	|
 | -i INT	|	Maximum distance from the start/end of an exon to annotate a variant as relevant to splicing, the variant is in intronic space. [2]	|

docs/commands/commands.md

@@ -13,6 +13,7 @@ This set of tools helps identify and work with aberrant splicing events near var
 Below are links to detailed explanations of the `cis-splice-effects` sub-commands:
 
 - [identify](cis-splice-effects-identify.md)
+- [associate](cis-splice-effects-associate.md)
 
 ##cis-ase
 This set of tools helps identify and work with allele-specific-expression near variants, these could be somatic variants or germline polymorphisms/mutations. These variants are hypothesized to act in cis and affect how the gene is transcribed.

docs/commands/junctions-extract.md

@@ -18,7 +18,7 @@ The `junctions extract` command can be used to extract exon-exon junctions from
 | -o      | File to write output to. STDOUT by default.|
 | -r      | Region to extract junctions in. This is specified in the format "chr:start-end". If not specified, junctions are extracted from the entire BAM file.|
 | -h      | Display help message for this command.|
-| -s      | Strand specificity of RNA library preparation, where 0 = unstranded, 1 = first-strand/RF, 2 = second-strand/FR. The default is 1 (RF). This option is meant to be used if no XS tags are present in the input BAM.
+| -s      | Strand specificity of RNA library preparation, where 0 = unstranded/XS, 1 = first-strand/RF, 2 = second-strand/FR. This option is required. If your alignments contain XS tags, these will be used in the "unstranded" mode. 
 
 ###Output
 The output is in the BED12 format which is described in detail [here.](https://genome.ucsc.edu/FAQ/FAQformat.html#format1) Each line is an exon-exon junction as explained below.