===================
Seqliner QuickStart
===================

Basics
======

Once you or your site admin have made Seqliner available in your system (see `Installation Guide`_), simply type ``seqliner`` to get the list of commands::

    >> seqliner

    seqliner: A toolkit for effective use and management of bioinformatics pipelines.

    <Subcommands>

      list           lists available pipelines
      run            runs a pipeline
      config         creates a config template where pipeline parameters can be customized.
      dev            more tools for developers.
      admin          tools for administering pipelines and resources.

    <Others>

      --version      get version


.. ..

To browse the list of available pipelines and recipes, type ``seqliner list``. Listing options can be obtained via ``seqliner list --help``::

    >> seqliner list

    ====================
    == Pipelines =======
    ====================
    ===== amplicon ===============================================================
        Desc: Amplicon pipeline. Performs alignment (Primal Aligner) & Variant
              Calling (VarScan),
      Inputs: <dir, fasta>   Sample directory containing fastq pair(s), fasta file
     Outputs: <vcf,bam,...> Variant call by VarScan, bam files from PrimalAligner
              and more.

    ===== germline ===============================================================
        Desc: Germline pipeline. Performs alignment, duplicate marking, indel
              realignment, base quality recalibration, performance summary,
              variant calling.
       Input: <dir>   Sample directory containing fastq pair(s)
     Outputs: <vcf,bam,...> Variant call by GATK, performance summary, bam files
              and more.

    ===== somatic ================================================================

            :
            :

    ====================
    == Recipes =========
    ====================
           RECIPE  DESCRIPTION
            hg19 : Defines reference and data resources for HG19
            mm10 : Defines reference for MM10 (TODO: known snps & known indels)
       idt_borca : Defines IDT_BORCA target regions
         nimb_v3 : Defines NimbleGen Exome V3 target regions
      agilent_v4 : Defines Agilent SureSelect Human Exome V4 target regions
       pairedEnd : Data is paired-end.
       singleEnd : Data is single-end.
            :
            :

.. ..


From the description above, you should be able to work out A) the intended use of the pipelines, B) expected inputs, and C) relevant recipes.
If you can't, make a complaint to the pipeline developers!!

Once you know what pipeline and recipes to use, you are ready to run a pipeline. Just type ``seqliner run`` to get a description of the syntax::

    >>seqliner run

    USAGE: seqliner run <pipeline> [options] [input1[ input2[ ...]]]

    <Required>
     pipeline : See 'seqliner list' for a list of available pipelines

    <Optional>
         -r : Comma separated recipes (e.g. hg19,SureSelectHuExomeV4)
         -o : Output directory [default: current working dir]
         -c : Custom config (see 'seqliner config'). Settings in this file will
              override recipes (if overlaps) and site config.
         -d : Custom script directory
         -p : Additional parameter(s) required by pipeline; comma separated
              key-value pairs (e.g. RUN_ID=001,SAMPLE_LABEL=003).
         -t : RESOURCE ROOT. Default root directory for resource files unless full
              path is specified

    <Notes>
     --rerun  : Use 'seqliner run --rerun <params-log.groovy>' to perform a rerun
                using previously supplied arguments
     -f false : inputs will be converted to full path by default. Use '-f false'
                to suppress
     -q true  : seqliner will use bpipe built-in qsub handler (default: false)

.. ..

For example, to analyse a germline sample that has been target-enriched using the Agilent SureSelect Human All Exon v4 capture,
we will be using the "germline" pipeline and the "hg19" and "agilent_v4" recipes, which were all described when we typed ``seqliner list`` above.
Now, we use ``seqliner run`` as follows: ::

    >> seqliner run germline -r hg19,agilent_v4 -o myOutDir /path/to/germline/fastq/dir

If you are running this in a compute cluster environment, either use -q or do a normal job submission: ::

    >> seqliner run germline -q -r hg19,agilent_v4 -o myOutDir /path/to/germline/fastq/dir

OR::

    >> echo "cd $PWD; seqliner run germline -r hg19,agilent_v4 -o myOutDir /path/to/germline/fastq/dir" | qsub -l walltime=48:00:00,mem=16GB

To customise pipelines and/or use custom configurations (e.g. for a custom capture panel), one of the ``-c`` / ``-d`` / ``-p`` parameters can be used. Full documentation is available in :doc:`/configuration`.

We also recommend reading and understand the :doc:`Roles concept </roles>` underlying the design of Seqliner.

Installation Guide
==================

To do.