diff --git a/docs/getting_started/img/1.1.png b/docs/getting_started/img/1.1.png new file mode 100644 index 0000000..22ba0ae Binary files /dev/null and b/docs/getting_started/img/1.1.png differ diff --git a/docs/getting_started/img/2.1.png b/docs/getting_started/img/2.1.png new file mode 100644 index 0000000..a048d64 Binary files /dev/null and b/docs/getting_started/img/2.1.png differ diff --git a/docs/getting_started/installation.rst b/docs/getting_started/installation.rst index 26555ff..3fd5822 100644 --- a/docs/getting_started/installation.rst +++ b/docs/getting_started/installation.rst @@ -504,10 +504,10 @@ Next, follow along this video when creating your Docker container from Iliad's D -Step 1: Download and Install Docker Desktop +Step 1: Download, Install, and Configure Docker Desktop ******************************************* -Follow instructions here: https://www.docker.com/products/docker-desktop/ +Follow instructions here to download and install Docker Desktop: https://www.docker.com/products/docker-desktop/ IF YOU NEED TO USE EXTERNAL DRIVE: Create a symlink to External Drive to preserve internal drive. **Replace and accordingly** @@ -518,6 +518,20 @@ Create a symlink to External Drive to preserve internal drive. **Replace /Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw /Volumes//Users//Library/Containers/com.docker.docker/ $ ln -s /Volumes//Users//Library/Containers/com.docker.docker/Docker.raw /Users//Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw +Edit Resource Settings in the Docker Desktop like so: + +.. image:: img/1.1.png + :align: center + :width: 800 + +Find Settings + +.. image:: img/2.1.png + :align: center + :width: 800 + +Find Resources and adjust CPUs (6), Memory (30 GB), and Virtual disk limit (~500 GB) + Step 2: Pull image from Docker ****************************** @@ -536,3 +550,133 @@ This creates a container based on the Iliad Docker Image that you can enter and If you ever ``exit`` your container, you can re-enter with ``docker exec -it bash`` +Step 4: Clone the Iliad repository and workflows +************************************************ + +.. Given that Snakemake and Snakedeploy are installed and available (see Step 1), the workflow can be deployed as follows. + +First, create an appropriate project working directory (/path/to/project) on your system and enter it: + +.. code-block:: console + + $ cd /usr/ + $ mkdir -p project + $ cd project + +In the next step, you will clone the Iliad repo. This will create an Iliad directory that you will cd into. +If you are not an active github user, you may have to create an account and a personal access token that is entered +for password when prompted to do so on the command line in the following step. +Here is a link for token_ information and creation_. + +.. **OPTION 1: snakedeploy** + +.. .. code-block:: console + +.. $ snakedeploy https://github.com/ncherric/Iliad . --tag v1.0.0 +.. $ cd Iliad + +**Clone the repository using git:** + +.. Git clone the `GitHub repository `_. + +.. code-block:: console + + $ git clone https://github.com/ncherric/Iliad.git + $ cd Iliad + +Now, there should be an ``./Iliad`` directory cloned into your ``/path/to/project/`` like such ``/path/to/project/Iliad/``. +And your current working directory should be ``/path/to/project/Iliad/``. + +Two important folders found in the Iliad directory are **workflow** and **config**. +The ``workflow`` contains rules and scripts that a designated Snakefile in Iliad call on to run a specific module. +The ``config`` contains one configuration file ``Iliad/config/config.yaml`` which will be modified in the next step in order to configure the workflow to your needs. +It also contains ``Excel`` files and ``TSV`` files where you will input your sample information. + +.. **side note** +.. ( Once this pipeline is publicly available, and added to the Snakemake Workflow Catalog, run below. For now, just **clone ABOVE** ) + + +Step 5: Configure Workflow +************************** + +There are 2 methods: Automatic and Manual + +**A) Automatic** + +.. code-block:: console + + $ cd config + $ python auto_config.py + $ mv modified.yaml config.yaml + $ cd .. + +There will be interactive questions on the command line that will ask you to enter your 1) working directory 2) sample table file with download URLs and 3) reference assembly info for download. +Answer the interactive prompts accordingly and then press RETURN/ENTER. +NOTE: Using this command-line interactive prompt to update the config.yaml file will erase all comments and notes in your `config.yaml` file. +There is an additional `config-commented.yaml` that you can refer to if you have questions about settings. + + +**B) Manual** + +To configure this workflow, modify ``Iliad/config/config.yaml`` according to your needs. +The file is clearly denoted into sections that you can change according to your needs. +There are many defaults set that you do not have to change. The one most important change you will have to make is the following: + +.. code-block:: console + + $ nano config/config.yaml + +And INSERT your working directory path where NEED PATH HERE is. should look like this: **/path/to/project/Iliad/** + +.. code-block:: yaml + + ##################################### + ##################################### + ##################################### + + # # # USER INPUT VARIABLES # # # + + ##################################### + ##################################### + ##################################### + + # You must insert your /PATH/TO/Iliad/ + # use 'pwd' command to find your current working directory when you are inside of Iliad directory + # e.g. /path/to/Iliad/ <---- must include forward slash at the end of working directory path + + # must include forward slash, '/', at the end of working directory path + workdirPath: NEED PATH HERE + + +Step 6: Run workflow +******************** + +Given that the workflow has been properly deployed and configured, and your conda environment is activated, it can be executed as follows. + +For running the workflow while deploying any necessary software via singularity and conda (using the Mamba package manager by default), run Snakemake with + +.. code-block:: console + + $ snakemake -p --use-conda --cores 1 --jobs 1 --default-resource=mem_mb=10000 --latency-wait 120 + +Other workflows +******************** + +When executing the workflow, Snakemake will automatically find the main Snakefile in the workflow subfolder which is the **Raw Sequence Read Data** module. +However, there are other Snakefiles that are specific to the other Modules that you will have to call using ``--snakefile [desired module snakefile]`` + +* ``--snakefile workflow/Snakefile`` -> Raw Sequence Read Data +* ``--snakefile workflow/cram_Snakefile`` -> Stored Sequence Read Data +* ``--snakefile workflow/snpArray_Snakefile`` -> SNP Array Data +* ``--snakefile workflow/LiftoverTo38_Snakefile`` -> Submodule to liftover GRCh37 assembly VCF data to GRCh38 assembly +* ``--snakefile workflow/LiftoverTo37_Snakefile`` -> Submodule to liftover GRCh38 assembly VCF data to GRCh37 assembly +* ``--snakefile workflow/merger_Snakefile`` -> Submodule to merging list of VCFs +* ``--snakefile workflow/mergeRefTarget_Snakefile`` -> Submodule that will merge your processed Reference and Target data if you have previously completed both modules + +Visit the How-To Guides pages for further info about each of the Modules and Submodules in the bulleted list above. + +This example bewlow is for the `Stored Sequence Read Data `_ + +.. code-block:: console + + $ snakemake -p --use-conda --cores 1 --jobs 1 --snakefile workflow/cram_Snakefile --default-resource=mem_mb=10000 --latency-wait 120