Metadata-Version: 2.1
Name: mitoz
Version: 3.3
Home-page: https://github.com/linzhi2013/MitoZ
Author: Guanliang Meng
Author-email: linzhi2012@gmail.com
License: GPLv3
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GPLv3 License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3
License-File: LICENSE

**See https://github.com/linzhi2013/MitoZ/releases/ and https://github.com/linzhi2013/MitoZ/wiki for more details**


# 1. About MitoZ

MitoZ is a Python3-based toolkit which aims to automatically filter pair-end raw data (fastq files), assemble genome, search for mitogenome sequences from the genome assembly result, annotate mitogenome (genbank file as result), and mitogenome visualization. MitoZ is available from `https://github.com/linzhi2013/MitoZ`.


# 2. System requirment

## 2.1 Platform

MitoZ is developed and tested under `Linux version 2.6.32-696.el6.x86_64 (mockbuild@c1bm.rdu2.centos.org) (gcc version 4.4.7 20120313 (Red Hat 4.4.7-18) (GCC) ) #1 SMP Tue Mar 21 19:29:05 UTC 2017`.

## 2.2 Harddisk space

\>50 GB

## 2.3 Memory

- `--assembler mitoassemble`: It takes ~100G when we tested MitoZ with `--thread_number 16`. This is because MitoZ uses the *de Bruijn* graph (DBG) algorithm to perform *de novo* assembly. To learn more, see https://doi.org/10.1093/bioinformatics/btu077.


- `--assembler spades` and `--assembler megahit`: You can use the `--memory` option to control how much RAM you are going to use. But beware: setting this too low could make the program halt or exit. Typically, `~16GB to 50GB` of RAM still required.

there are ways to reduce the memory usage:
1. enrich the mitochondrion during experiment step (e.g. via gene capture array).
  This can lead to a higher mitochondrial derived reads ratio in the HTS data, and then you can use less data for MitoZ input,
which can reduce memory usage of MitoZ.

2. filter out the mitochondrial reads by mapping reads against mitogenomes of closely-related species (if any).
  provide such reads (a smaller volume of data) to MitoZ.

**Warning**:
Use too many threads (e.g. > 16) can be problematic, the assembly step can get stuck and seems never finished.  

# 3. Data requirement

## 3.1 Material source

The most preferable data for mitochondrial genome assembly is always data with high
ratio of mitochondrial derived reads and little contamination. For example, tissue samples
may be better than blood samples or gut samples.

UCE data might also work.

## 3.2 Requirment of data size and insert size

About 1.5 to 3G base pair (bp) is enough for mitochondrial genome assembly.

e.g. `raw.1.fq.gz` and `raw.2.fq.gz` or `clean.1.fq.gz` and `clean.2.fq.gz`


The insert size of pair-end library should be small insert size (<1000 bp). I do not recommend to use data of large insert size (>1000bp, mate-pair library), because this kind of data usually is not good as small insert size data.


## 3.3 Single-end data or pair-end data

Most modules support both single-end and pair-end data. But the SPAdes assembler currently only support pair-end data.

**NB:  since single-end data lacks pairing information that is useful in the scaffolding step, it may not be able to generate mitochondrial genome assembly of quality as good as that generated using paired-end data.**


## 3.4 Fasta file

When you annotate a mitogenome sequence(s) stored in fasta file, the sequence id can not be too long, or MitoZ will fail. This is for some limitation in BioPython that MitoZ invokes.


## 3.5 Genetic code

It is important to set a correct genetic code for MitoZ (`--genetic_code` option). Usually, arthropods use the invertebrate mitochondrial code (`--genetic_code 5`), and mammals use the vertebrate mitochondrial code (`--genetic_code 2`).Please refer to https://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi for more details.

MitoZ use the genetic code for annotating the Protein coding genes (PCGs) of mitochondrial genome.


## 3.6 Taxa group

It is also important to set a correct taxa group for MitoZ (`--clade` option).

MitoZ use the `--clade` option to choose corresponding database (HMM modules, CM modules, protein reference sequences).

# 4. Results
Files in `ZZZ.result` including:

<br>

1. `README.txt`

A brief instruction about each file in the `ZZZ.result` directory.

<br>

2. `summary.txt`
 
A summary about the mitogenome in `ZZZ_mitoscaf.fa.gbf` (or the `*.mitogenome.fa` file
if you run `assemble` or `findmitoscaf` module), including a list of genes,
numbers of genes recovered totally, what genes may be missing (if any), the sequence length,
circularity, most closely related species.

<br>

3. `circos.png` and `circos.svg`

Visualizations of the mitogenome in `ZZZ_mitoscaf.fa.gbf`.

<br>

4. `ZZZ_mitoscaf.fa.gbf`, `ZZZ.fasta`, `ZZZ_mitoscaf.fa.sqn` and `ZZZ_mitoscaf.fa.tbl`.

The mitogenome files in different format. **The sequences whose sequence ids have
`_FivePCGs` suffixs (if any) are not considered as our mitogenome of target species,
and they are output intendedly for further inspection by users**. All sequences with ≥ 5
PCGs besides the mitochondrial sequences will be output by MitoZ intendedly.

If you run the `assemble` or `findmitoscaf` modules, the `ZZZ.fasta` file will be `work71.mitogenome.fa`.
We do not rename `work71.mitogenome.fa` to be `ZZZ.fasta` to aovid overwriting the `ZZZ.fasta` file if you run
MitoZ in multi-kmer mode.


<br>

5. `ZZZ.cds`, `ZZZ.rrna`, `ZZZ.trna` and `ZZZ.misc_feature`

The individual gene sequences in fasta format, extracted from `ZZZ_mitoscaf.fa.gbf`.

<br>

6. `ZZZ_mitoscaf.fa.val` and `errorsummary.val`

The two files are generated by NCBI's tbl2asn program, describing related warnings and
errors for file `ZZZ_mitoscaf.fa.gbf`. Thus, **you should check this file to confirm if
there are any assembly or annotation problems**.

For example, an InternalStop for protein coding genes can be caused by assemlby (e.g.,
there are Ns, or assembly errors), annotation, mutation, incorrect genetic code, or the
sequence simply comes from nuclear mitochondrial DNA segments (NUMTs). You may inspect
the sequencing depth distribution of sequences around such regions from the
visualization result files (`circos.png` and `circos.svg`).

<br>

7. `work71.mitogenome.fa` and `work71.most_related_species.txt`

The mitogenome sequences from each kmer (e.g. kmer 71) assembly and their most closely
related species.

* If you run `all` or `all2` module, you can ignore the two files, `work71.mitogenome.fa` is
the same as `ZZZ.fasta` file, while `work71.most_related_species.txt` is the same as
`ZZZ.most_related_species.txt`.

* If you run `assemble` or `findmitoscaf` module, the `work71.mitogenome.fa` or
`outprefix.mitogenome.fa` is your mitogenome file.

* If you run MitoZ in multi-kmer mode, if one kmer assembly has very good results, then you
can just use these two files as your mitogenome files, instead of the file
`outprefix.multiKmer_seq_picked.clean.fa` (describled in **section 13.1** as below)

<br>

*Below file are not part of the final mitogenome results, but are output just in case the
users want to know more about those information instead of the mitogeome of target species*.

8. `work71.hmmtblout.besthit.sim.filtered.high_abundance_10.0X.reformat.sorted.Not-picked`, `work71.hmmtblout.besthit.sim.filtered.high_abundance_10.0X.reformat.sorted.Not-picked.fa`, `work71.hmmtblout.besthit.sim.filtered.low_abundance` and `work71.hmmtblout.besthit.sim.filtered.low_abundance.fasta`

These `*.low_abundance*` and `*.high_abundance*` files, which are the sequences with low abundances
or high abundances but not selected as outputs by MitoZ.

*These sequences, together with the sequences whose sequence ids have `_FivePCGs` suffixs in
`ZZZ_mitoscaf.fa.gbf` and `ZZZ.fasta` (if any), may be useful if, for
example, you want to find potential NUMTs, or want to know if there are some sequences
of non-target-species*.

<br>

When you use other modules, some of those files (directories) may be absent.


# 5. How good is my result?

There are several aspects you should consider:

1. The sequencing depth along the mitochondrial sequence(s)

Check the `circos.png` or `circos.svg` files

2. Internal stop codons within PCGs

3. Circularity of your mitochondrial sequence

Check the `summary.txt`

4. Is there any gene missing?

Sometimes, even when the result mitogenome is complete ('circular'), due to the limitation of annotation progrom, e.g., MiTFi for tRNA, some tRNA genes can still be missing.

5. Can my result sequences be contaminations or NUMTs?

Blast your result sequences again NCBI NT database.

# 6. Citations

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.

**WHEN YOU ADAPT (PART OF) THE SOFTWARE FOR YOUR USE CASES, THE AUTHOR AND**
**THE SOFTWARE MUST BE EXPLICITLY CREDITED IN YOUR PUBLICATIONS AND SOFTWARE,**
**AND YOU SHOULD ASK THE USERS OF YOUR SOFTWARE TO CITE THE SOFTWARE IN**
**THEIR PUBLICATIONS. IN A WORD, 请讲武德.**

COPYRIGHT 2019-2022 Guanliang Meng. ALL RIGHTS RESERVED.

When you use MitoZ, please cite:
```
Meng, G., Li, Y., Yang, C., & Liu, S. (2019). MitoZ: a toolkit for
animal mitochondrial genome assembly, annotation and visualization.
Nucleic acids research, 47(11), e63-e63. https://doi.org/10.1093/nar/gkz173
```
Additionaly, you SHOULD also CITE related software invoked by MitoZ,
without them, MitoZ will not make its way. 

- fastp # for the `all` or `filter` subcommand (MitoZ version >= 3.0)
- soapdenovo-trans # for the `all` or `assemble` subcommand
- Megahit # for the `all` or `assemble` subcommand
- SPAdes # for the `all` or `assemble` subcommand
- hmmer # for the `all` or `assemble` or `findmitoscaf` subcommand
- blast # for the `all` or `assemble` or `findmitoscaf` or `annotate` subcommand
- genewise # for the `all` or `assemble` or `findmitoscaf` or `annotate` subcommand
- infernal # for the `all` or `annotate` subcommand
- MiTFi # for the `all` or `annotate` subcommand
- cricos # for the `all` or `annotate` or `visualize` subcommand
- bwa # for the `all` or `annotate` or `visualize` subcommand and you draw the sequencing coverage distribution track
- samtools # for the `annotate` or `visualize` subcommand and you draw the sequencing coverage distribution track

Please refer to the MitoZ paper for the reference details.

