update doc and strand opp

Author: nchenche

.gitignore

@@ -2,6 +2,8 @@
 # Orfmap data            #
 ##########################
 orfmap/data/*
+orfmap/data/scerevisiae/mapping*
+orfmap/data/scerevisiae/*/mapping*
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -1,17 +1,21 @@
-ORFMap
-===========
-
+# ORFMap
 ORFMap - A tool aimed at scanning a genome for stop-codons delimited sequences (ORFs) and annotating them.
 
+## Summary
+* <p><a href="#descr">Description</a></p>
+* <p><a href="#installation">Installation</a></p>
+* <p><a href="#usage_descr">Usage description</a></p>
+* <p><a href="#usage_ex">Some usage examples</a></p>
 
-
-Description
------------
+<h2><a name="descr">Description</a></h2>
 
 From a genomic fasta file and its associated GFF, the program first scans the genome to retrieve all sequences
 delimited by stop codons. Only sequences of at least 60 nucleotides long are kept by default.
 
-Those so-called ORF sequences are then annotated depending upon GFF element type(s) used as a reference. The CDS element type is always used as a reference but others can be added. By default an ORF sequence has 5 possible annotations:
+Those so-called ORF sequences are then annotated depending upon GFF element type(s) used as a reference.
+The CDS element type is always used as a reference but others can be added.
+
+By default an ORF sequence has 5 possible annotations:
 
 | ORF annotation | Condition |
 | --- | --- |
@@ -21,9 +25,11 @@ Those so-called ORF sequences are then annotated depending upon GFF element type
 | nc_ovp-CDS | if the ORF overlap with a CDS in a different phase |
 | nc_intergenic | if the ORF do not overlap with anything |
 
-**Note** that if an ORF sequence is tagged as 'c_CDS', this sequence is further processed to be cut at its 5' and 3' extremities that do not overlap with the CDS. If their length is above or equal to 60 nucleotides, then those subsequences can be assigned as nc_5-CDS and/or nc_3-CDS.
+**Note:** 
+If an ORF sequence is tagged as 'c_CDS', this sequence is further processed to be cut at its 5' and 3' extremities that do not overlap with the CDS. If their length is above or equal to 60 nucleotides, then those subsequences can be assigned as nc_5-CDS and/or nc_3-CDS.
+ <br></br>
+ <br></br>
 
-
 The user can also specify what GFF element type(s) can be used as reference(s) to annotate ORF sequences in addition to the CDS type. For instance, if the user adds the tRNA element type, ORF sequences could now be assigned as nc_ovp-tRNA if they overlap with a tRNA. Thus 6 assignments would now be possible for an ORF sequence:
 
 | ORF annotation | Condition |
@@ -36,93 +42,122 @@ The user can also specify what GFF element type(s) can be used as reference(s) t
 | nc_intergenic | if the ORF do not overlap with anything |
 
 **Note on default parameters**:
-* CDS in the only element type used as a reference to annotate ORF sequences.
+* CDS is the only element type used as a reference to annotate ORF sequences.
 * the minimum nucleotide number required to consider an ORF sequence is set at 60 nucleotides
 * an ORF sequence is considered as overlapping with an element (e.g. CDS) if at least 70 % of its sequence overlap with the element or if this element is totally included within the ORF sequence
 
 
-----------------------------------------
-Installation procedure from distribution
-----------------------------------------
+<h2><a name="installation">Installation</a></h2>
 
+### 1. Download and uncompress the latest release archive
 
-I. First steps
-------------
+#### Download the latest release
+Latest release: 
+[ ![](./docs/images/download-flat/16x16.png "Click to download the latest release")](https://github.com/nchenche/orfmap/releases/latest/)
 
-1. Uncompress and untar the package:
+#### Uncompress the archive
+If you downloaded:
+* the *.zip* file: ```unzip ORFMap-x.x.x.zip```
+* the *.tar.gz* file: ```gunzip ORFMap-x.x.x.tar.gz | tar xvf```
+
+
+### 2. Create an isolated environment
+Although not strictly necessary, this step is highly recommended (it will allow you to work on different projects without having
+any conflicting library versions).
+ 
+#### Install virtualenv
+``` python
+python3 -m pip install virtualenv
+```
 
+#### Create a virtual python3 environment
 ```bash
-tar -xzvf orfmap-0.0.tgz
+virtualenv -p python3 my_env
 ```
 
-2. Go to the ORFMap directory
- 
+#### Activate the created environment
 ```bash
-cd ORFMap-0.0
+source my_env/bin/activate
 ```
 
+Once activated, any python library you'll install using pip will be installed solely in this isolated environment.
+Every time you'll need to work with libraries installed in this environment (i.e. work on your project), you'll have
+to activate it. 
 
-II. Install the package in a virtual environment (the recommended way to avoid dependencies conflict)
-------------------------------------------------------------------
+Once you're done working on your project, simply type `deactivate` to exit the environment.
 
-1. Install virtualenv (if necessary)
 
-```bash
-pip install virtualenv
-```
+### 3. Install ORFMap in your isolated environment
 
-2. Create a virtual environment (for python3)
+Be sure you're virtual environment is activated, and then follow the procedure described below.
 
+#### Go to the ORFMap directory
+ 
 ```bash
-virtualenv -p python3 env_orfmap
+cd ORFMap-x.x.x/
 ```
 
-3. Activate your virtual environment
+#### Install 
 
-```bash
-source env_orfmap/bin/activate
+```python
+python setup.py install
 ```
 
-**Note that once activated:**:
-* you should see the name of your virtual environment in brackets on your terminal line
-* any python commands will now work within your virtual environment
-	
-
+or 
+```python
+pip install .
+```
 
-4. Install ORFMap in your virtual environment
 
-```bash
-python setup.py install
-```
+<h2><a name="usage_descr">Usage description</a></h2>
 
-**Note**: once installed, you should be able to run orfmap (see below). Once you don't need to use it, you can deactivate or exit your virtual environment by executing in the terminal:
+To see all options available:
 
-```bash
-deactivate
+```
+run_orfmap -h
 ```
 
-From this installation, everytime you'll want to use orfmap you'll need to activate your dedicated virtual environment.
+This command will show:
 
+<pre>usage: run_orfmap [-h] -fna [FNA] -gff [GFF] [-chr [CHR]] [-types_only TYPES_ONLY [TYPES_ONLY ...]]
+                  [-types_except TYPES_EXCEPT [TYPES_EXCEPT ...]] [-o_include O_INCLUDE [O_INCLUDE ...]] [-o_exclude O_EXCLUDE [O_EXCLUDE ...]]
+                  [-orf_len [ORF_LEN]] [-co_ovp [CO_OVP]] [-out [OUT]] [--show-types] [--show-chrs]
 
+Genomic mapping of pseudo-ORF
 
-II_bis. Install the package in the standard python libraries of your system (not recommended)
----------------------------------------------------------------------------------------------
+optional arguments:
+  -h, --help            show this help message and exit
+  -fna [FNA]            Genomic fasta file (.fna)
+  -gff [GFF]            GFF annotation file (.gff)
+  -chr [CHR]            Chromosome name
+  -types_only TYPES_ONLY [TYPES_ONLY ...]
+                        Type feature(s) to use as reference(s) (&apos;CDS&apos; in included by default).
+  -types_except TYPES_EXCEPT [TYPES_EXCEPT ...]
+                        Type feature(s) to not consider as reference(s) (None by default).
+  -o_include O_INCLUDE [O_INCLUDE ...]
+                        Type feature(s) and/or Status attribute(s) desired to be written in the output (all by default).
+  -o_exclude O_EXCLUDE [O_EXCLUDE ...]
+                        Type feature(s) and/or Status attribute(s) desired to be excluded (None by default).
+  -orf_len [ORF_LEN]    Minimum number of nucleotides required to define a sequence between two consecutive stop codons as an ORF sequence (60
+                        nucleotides by default).
+  -co_ovp [CO_OVP]      Cutoff defining the minimum CDS overlapping ORF fraction required to label on ORF as a CDS. By default, an ORF sequence
+                        will be tagged as a CDS if at least 70 per cent of its sequence overlap with the CDS sequence.
+  -out [OUT]            Output directory
+  --show-types          Print all type features
+  --show-chrs           Print all chromosome names
+</pre>
 
-In ORFMap-0.0/:
+Except -fna and -gff arguments that are mandatory, all others are optional.
 
-```bash
-python setup.py install
-```
 
+### Basic run
 
-----------------------------------------
-Running ORFMap
-----------------------------------------
+ORFMap requires two input files: 
+* a genomic fasta file (-fna)
+* its associated GFF file (-gff).
 
-Basic run
----------
 
-ORFMap requires two input files: a genomic fasta file (-fna) and its associated GFF file (-gff). The most basic run can be executed by typing:
+The most basic run can be executed by typing:
 
 ```
 run_orfmap -fna mygenome.fna -gff mygenome.gff
@@ -146,100 +181,69 @@ The output will be two separated files with the prefix "mapping_orf_":
 By default, the two output files will contain all possible 5 annotations mentionned above.
 
 
-Usage description
------------------
-
-To see all options available:
-
-```
-run_orfmap -h
-```
+<h2><a name="usage_ex">Some usage examples</a></h2>
 
-This command will show:
+By default, all element types (except 'region' and 'chromosome') found in the GFF file are used as reference
+to annotate ORF sequences. If an ORF sequence overlaps with more than 2 elements, then the ORF sequence will be assigned
+according to the element with which it overlaps the most. For instance, let's say an ORF sequence overlaps at 85% with
+a tRNA and at 90% with a sRNA, then the ORF will be assigned as nc-ovp_sRNA.
+Note that the CDS element type always has the priority relative to any other element types. Therefore, if an ORF 
+sequence overlaps at 72% with a CDS and at 95% with an other element that is not a CDS, then the ORF will be assigned as
+c_CDS. When an ORF sequence entirely overlaps with multiple elements, then the choice for its  assignment is quite
+arbitrary : the ORF will be assigned depending on the first element met in the GFF. That case could appear for 
+intrinsically related elements such as gene, exon and mRNA. For example, let's say an ORF sequence equally overlaps with
+an exon and a gene region (but there's no overlap with the CDS part). Since the gene normally appears firt in the GFF 
+file, the ORF will be assigned as nc-ovp_gene. In order to avoid those special cases, an option allows the user specify 
+element types that should not be considered as reference for the ORF assignment. 
 
-usage: run_orfmap [-h] -fna [FNA] -gff [GFF] [-type TYPE [TYPE ...]] [-o_include O_INCLUDE [O_INCLUDE ...]] [-o_exclude O_EXCLUDE [O_EXCLUDE ...]] [-orf_len [ORF_LEN]]
-                  [-co_ovp [CO_OVP]] [-out [OUT]]
 
-Genomic mapping of pseudo-ORF
 
 
-| Arguments | Description |
-| --- | --- |
-| -h, --help | show this help message and exit |
-| -fna [FNA] | Genomic fasta file (.fna) |
-| -gff [GFF] | GFF annotation file (.gff) |
-| -type TYPE [TYPE ...] | Type feature(s) a flag is desired for ('CDS' in included by default). |
-| -o_include O_INCLUDE [O_INCLUDE ...] | Type feature(s) and/or Status attribute(s) desired to be written in the output (all by default). |
-| -o_exclude O_EXCLUDE [O_EXCLUDE ...] | Type feature(s) and/or Status attribute(s) desired to be excluded (None by default). |
-| -orf_len [ORF_LEN] | Minimum number of nucleotides required to define a sequence between two consecutive stop codons as an ORF sequence (60 nucleotides by default). |
-| -co_ovp [CO_OVP] | Cutoff defining the minimum CDS overlapping ORF fraction required to label on ORF as a CDS. By default, an ORF sequence will be tagged as a CDS if at least 70 per cent of its sequence overlap with the CDS sequence. |
-| -out [OUT] | Output directory |
+In the case where an ORF sequence overlaps 
 
-
-Except -fna and -gff arguments that are mandatory, all others are optional.
-
-| Arguments | Default value |
-| --- | --- |
-| -type | CDS |
-| -o_include | 'all' |
-| -o_exclude | None |
-| -orf_len | 60 |
-| -co_ovp | 0.7 |
-| -out | './' |
+##### Use tRNA and snRNA element as a reference to annotate ORF sequences:
+```
+run_orfmap -fna mygenome.fna -gff mygenome.gff -types_only tRNA snRNA -out myResults
+```
 
 
-Usage examples
------------------
 
-This command will use tRNA and snRNA element types as a reference to annotate ORF sequences and the outputs will be created in myResults/
+##### Use tRNA and snRNA element as a reference to annotate ORF sequences:
 ```
-run_orfmap -fna mygenome.fna -gff mygenome.gff -type tRNA snRNA -out myResults
+run_orfmap -fna mygenome.fna -gff mygenome.gff -types_only tRNA snRNA -out myResults
 ```
 
-7 annotations will be possible for an ORF sequence:
-
-| ORF annotation | Condition |
-| --- | --- |
-| c_CDS |if the ORF overlap with a CDS in the same phase |
-| nc_5-CDS | if the 5' extremity of the c_CDS is at least 60 nucleotides long |
-| nc_3-CDS | if the 3' extremity of the c_CDS is at least 60 nucleotides long |
-| nc_ovp-CDS | if the ORF overlap with a CDS in a different phase |
-| nc_ovp-tRNA | if the ORF overlap with a tRNA |
-| nc_ovp-snRNA | if the ORF overlap with a snRNA |
-| nc_intergenic | if the ORF do not overlap with anything |
-
- 
-To make the output files having only ORF sequences mapped as nc_ovp-tRNA and nc_ovp-snRNA:
+##### Write in output files only ORF sequences mapped as nc_ovp-tRNA and nc_ovp-snRNA:
 ```
-run_orfmap -fna mygenome.fna -gff mygenome.gff -type tRNA snRNA -o_include nc_ovp-tRNA nc_ovp-snRNA -out myResults
+run_orfmap -fna mygenome.fna -gff mygenome.gff -types_only tRNA snRNA -o_include nc_ovp-tRNA nc_ovp-snRNA -out myResults
 ```
 
-To make the output files having all ORF sequences except those mapped as c_CDS:
+##### Write in output files all ORF sequences except those mapped as c_CDS:
 ```
 run_orfmap -fna mygenome.fna -gff mygenome.gff -type tRNA snRNA -o_exclude c_CDS -out myResults
 ```
 
-or:
+##### or:
 ```
 run_orfmap -fna mygenome.fna -gff mygenome.gff -type tRNA snRNA -o_exclude coding -out myResults
 ```
 
-**Note**: -o_include and -o_exclude take either feature types or a status attribute as arguments. Feature types have to be amongst the possible annotations for ORF sequences (e.g. c_CDS, nc_5-CDS, nc_intergenic...) while status attribute is either 'coding' or 'non-coding' ('coding' refers to c_CDS and 'non-coding' refers to the other ones).
+<em>Note</em>:
+<p>
+-o_include and -o_exclude take either feature types or a status attribute as arguments.
+Feature types have to be amongst the possible annotations for ORF sequences (e.g. c_CDS, nc_5-CDS, nc_intergenic...)
+ while status attribute is either 'coding' or 'non-coding' ('coding' refers to c_CDS and 'non-coding' refers to the other ones).
+ </p>
 
 
-
-This command will define ORF sequences if they are at least 50 nucleotides
+##### Assign ORF seqences if stop-to-stop length is at least 50 nucleotides:
 ```
 run_orfmap -fna mygenome.fna -gff mygenome.gff -orf_len 50
 ```
 
-
-This command will consider an ORF sequence as overlapping with an element (e.g. CDS) if at least 60 % of its sequence overlap with the element or if this element is totally included within the ORF sequence
+##### Consider an ORF sequence as overlapping with any element if at least 60 % of its sequence overlap with the element:
 ```
 run_orfmap -fna mygenome.fna -gff mygenome.gff -co_ovp 0.6
 ```
 
 
-
-
-

documentation/docs/annotation.md

@@ -0,0 +1,33 @@
+## ORF annotation
+
+All ORFs are annotated according to their potential overlapping GFF element(s).
+Globally, an ORF can be assigned either as a non-coding (nc) sequence or a coding (c) sequence.
+
+
+### Non-coding ORF sequences
+
+All GFF elements present in both strands are used to define if an ORF is overlapping or not. Thus, 
+non-coding ORF sequences have three possible feature types:
+
+* `nc_intergenic` if the ORF sequence has no overlapping GFF element
+* `nc_ovp-element_type` if the ORF sequence overlaps with a GFF element in the same strand
+* `nc_ovp-element_type-opp` if the ORF sequence overlaps with a GFF element in the opposite strand
+
+For instance, if an ORF sequence overlaps with a tRNA, the ORF type will be `nc_ovp-tRNA`.
+
+If an ORF sequence overlaps with multiple GFF elements, the one that will be considered to annotate 
+the ORF is the one selected according to the following priority sequence:
+
+ 1. an element on the same strand has the priority over an element on the opposite strand
+ 2. an element with which the ORF sequence overlaps the most has the priority over other elements
+ 3. the element appearing the first in the GFF file has the priority 
+
+
+
+
+If an ORF sequence overlaps with multiple GFF elements, the ORF type will be assigned according to
+the overlapping element with wich it overlaps the most. If the ORF overlaps equally with multiple 
+elements, then it will be arbitrarily assigned according to the first element met in the GFF file.
+
+
+ 

documentation/docs/download.md

@@ -0,0 +1 @@
+## Download

documentation/docs/img/icons/download_16x16.png

@@ -0,0 +1 @@
+,nicolas,nicolas-VivoBook-ASUSLaptop-X571GT-X571GT,09.11.2020 13:00,file:///home/nicolas/.config/libreoffice/4;