Usage
#####

Installation
************

To install with conda (preferred method)
========================================

To install rdeval with conda, first you should install conda (https://github.com/conda-forge/miniforge, please view the README.md on this page for further details), then rdeval using the following commands:

.. code-block:: console

   curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-$(uname)-$(uname -m).sh"
   bash Miniforge3-Linux-x86_64.sh

Once conda is installed, rdeval can then be installed using the following command:

.. code-block:: console

   conda create --name rdeval --channel conda-forge --channel bioconda --override-channels --strict-channel-priority rdeval

Before using rdeval, you will need to activate the conda environment created, using the following command:

.. code-block:: console

   conda activate rdeval


Standard installation
======================

Dependencies
------------
Rdeval relies on three libraries that should be correctly installed in your system:

* `Openssl <https://www.openssl.org/>`_, to compute md5sums
* `Htslib <https://github.com/samtools/htslib>`_, to work with BAM and CRAM files
* `zlib <https://github.com/madler/zlib>`_, required for the gzip compression and decompression

To use rdeval, you can either:

* download precompiled builds for your platform from the latest release `here <https://github.com/vgl-hub/rdeval/releases>`_
* :ref:`compile it from source <Compilation from source>`


Compilation from source
-----------------------

To compile rdeval you need the libraries listed in the :ref:`dependency section <Dependencies>` correctly installed under your path, and then simply run the following command in rdeval's main folder:

.. code-block:: console

   make -j


To use rdeval with the static linked binary (linux distribution only)
======================================================================

In cases where installation with conda or installing dependencies proves difficult, a fully static binary file is availble as a .zip file on the Releases page for rdeval, starting from v0.0.6 (https://github.com/vgl-hub/rdeval/releases). To use this binary file:

Download the binary .zip file to your linux machine.
Unzip the .zip file:

.. code-block:: console

   unzip rdeval.v0.0.6-linux-static.zip

Make the unzipped binary file executable:

.. code-block:: console

   chmod +x rdeval_static_binary

Run the executable binary file:

.. code-block:: console

   ./rdeval_static_binary rdeval/testFiles/random1.fasta


Troubleshooting the Installation
================================

If you run into issues when compiling rdeval, ensure you have the above dependencies installed.
Once you have confirmed they are installed, run the make clean command below, before rerunning the make -j command in rdevals main folder:

.. code-block:: console

   make clean
   make -j

Useful commands
***************

Help and Usage:
===============
To see a list of the usage of rdeval:

.. code-block:: console

   rdeval --help

Output size list, based on unsorted ('u'), sorted ('s'), histogram ('h') or inverse cumulative table ('c') [-s/--out-size]:
=================
.. code-block:: console

   rdeval -s u rdeval/testFiles/random1.fastq
   rdeval -s s rdeval/testFiles/random1.fastq
   rdeval -s h rdeval/testFiles/random1.fastq
   rdeval -s c rdeval/testFiles/random1.fastq

To generate a read summary:
===========================
.. code-block:: console

   rdeval -r rdeval/testFiles/random1.fasta

To generate stats:
==================
.. code-block:: console

   rdeval /path/to/data > /path/to/outfile.stats

To obtain a distribution of quality for each read (q) or both length and quality(a):
====================================================================================
.. code-block:: console

   rdeval rdeval/testFiles/random1.fastq -qq
   rdeval rdevaltestFiles/random1.fastq -qa

To generate a per-read report:
==============================
.. code-block:: console

   rdeval --sequence-report rdeval/testFiles/random1.fasta

To filter the reads to be assessed, by length ('l') or quality ('q'), or both:
==============================================================================
.. code-block:: console

   rdeval -f 'l>10' rdeval/testFiles/random1.fasta
   rdeval -f 'q>10' rdeval/testFiles/random1.fasta
   rdeval -f 'l>10 & q>10' rdeval/testFiles/random1.fasta

To exclude data from analysis, based on read header information in a list [-e/--exclude-list]:
==========================================================================
.. code-block:: console

   rdeval -e header.txt rdeval/testFiles/random1.fasta

To include data in the analysis, based on read header information in a list [-i/include-list]:
==========================================================================
.. code-block:: console

   rdeval -i header.txt rdeval/testFiles/random1.fasta

To write reads to a file or generate an rd summary file (output options: fa*[.gz], bam, cram, rd):
========================================================
.. code-block:: console

   rdeval -o output1.fa rdeval/testFiles/random1.fastq

To compress all the homopolymers longer than 'n' in the input:
==============================================================
.. code-block:: console

   rdeval --homopolymer-compress 1 rdeval/testFiles/random1.fastq

To subsample reads (requires an float between 0 and 1):
===================
.. code-block:: console

    rdeval --sample 0.5 rdeval/testFiles/random1.fastq

To make subsampling reproducible, use the '--random-seed <int>' option:
===================
.. code-block:: console

    rdeval --sample 0.5 --random-seed 1 rdeval/testFiles/random1.fastq

To print md5 of a .rd file:
===========================
.. code-block:: console

   rdeval --md5 rdeval/testFiles/random2.rd

To output data to a .rd file, then to run rdeval on the .rd file:
=============================
.. code-block:: console

   rdeval -o output1.rd rdeval/testFiles/random1.fastq
   rdeval output1.rd 
   rdeval output1.rd -qa
   
This can also be done on multiple files in parallel, combining the results at the end:
=============================
.. code-block:: console

   rdeval -o output1.rd rdeval/testFiles/random1.fastq
   rdeval -o output2.rd rdeval/testFiles/random2.fastq
   rdeval output1.rd output2.rd 
   rdeval output1.rd output2.rd -qa

To read a .bam or .cram file:
=============================
.. code-block:: console

   rdeval rdeval/testFiles/random3.bam
   rdeval rdeval/testFiles/random3.cram

To display the software version number [-v/--version]:
=======================================
.. code-block:: console

   rdeval -v 

Other command options are available by using the :ref:`help <Help and Usage>` function, described above.