addressing session 1 feedback

Author: mgeaghan

docs/session_1/1.3_configure.md

@@ -2,34 +2,25 @@
 
 !!! tip "Objectives"
 
-    - Learn how to customize the execution of an nf-core workflow.
-    - Customize a toy example of an nf-core workflow.
+    - Learn how to customize the execution of an nf-core workflow
+    - Customize a toy example of an nf-core workflow
 
 ## 1.3.1 Introduction to Nextflow configuration
 
-Nextflow pipelines are configured by way of special `.config` files. These files are used to set a wide variety of options that control how Nextflow runs, such as defining computing environments, specifying containerisation systems, and setting resources required by processes. They are also used to set various parameters of a pipeline.
+There are two ways in which we can control how nf-core and other Nextflow pipelines run: through Nextflow **configuration files** and through **workflow parameters**. Configuration files are special `.config` files which are used to set a wide variety of options that control how the Nextflow engine runs, such as defining computing environments, specifying containerisation systems, and setting resources required by processes. Workflow parameters, on the other hand, are specific to the pipeline you are running and are used to pass information to the pipeline such as sample information, filtering thresholds, reference files, etc.
 
 When a workflow is launched, Nextflow will look for configuration files in several locations. As each configuration file can contain conflicting settings, the sources are ranked to decide which settings to apply. Configuration sources are reported below and listed in order of decreasing priority:
 
-1. Parameters specified on the command line (`--parameter`)
-2. Parameters that are provided using the `-params-file` option
-3. Config files that are provided using the `-c` option
-4. The config file named `nextflow.config` in the current directory
-5. The config file named `nextflow.config` in the workflow project directory
-6. The config file `$HOME/.nextflow/config`
-7. Values defined within the workflow script itself (e.g., `main.nf`)
+1. Config files that are provided using the `-c` option
+2. The config file named `nextflow.config` in the current directory
+3. The config file named `nextflow.config` in the workflow project directory
+4. The config file `$HOME/.nextflow/config`
 
-Notably, while some of these files are already included in the nf-core workflow repository (e.g., the `nextflow.config` file in the nf-core workflow repository), others are automatically identified on your local system (e.g., the `nextflow.config` in the launch directory), and others are only included if they are specified using `run` options (e.g., `-params-file`, and `-c`). Understanding how and when these files are interpreted by Nextflow is critical for the accurate configuration of a workflows execution.
+Notably, while some of these files are already included in the nf-core workflow repository (e.g., the `nextflow.config` file in the nf-core workflow repository), others are automatically identified on your local system (e.g., the `nextflow.config` in the launch directory), and others are only included if they are specified using the `-c` option on the command line. Understanding how and when these files are interpreted by Nextflow is critical for the accurate configuration of a workflows execution.
 
 This system allows you to finely tune how Nextflow runs for you. An nf-core workflow will come with its own `nextflow.config` file, but you can use your own `nextflow.config` file in your launch directory to override the defaults. You can also have a config file at `$HOME/.nextflow/config` to set configuration options that you frequently use across pipelines.
 
-!!! warning "IMPORTANT!"
-
-    nf-core workflow **parameters** must be passed via the command line (`--<parameter>`) or Nextflow `-params-file` option. Custom config files, including those provided by the `-c` option, can be used to provide any configuration **except** for parameters.
-
-Each nf-core workflow has its own **configuration** and **parameter** defaults. Typically, the default parameters are chosen to be applicable to the average user, but you will almost certainly want to modify these to fit your own purposes and system requirements.
-
-Notably, configuration files can also contain the definition of one or more **profiles**. A profile is a set of configuration attributes that can be activated when launching a workflow by using the `-profile` command option:
+Notably, configuration files typically define of one or more **profiles**. A profile is a set of configuration attributes that can be activated when launching a workflow by using the `-profile` command option:
 
 ```bash
 nextflow run <workflow> -profile <profile>
@@ -38,10 +29,10 @@ nextflow run <workflow> -profile <profile>
 Profiles used by nf-core workflows include:
 
 - **Software management profiles**
-    - Profiles for the management of software using software management tools, e.g., `docker`, `singularity`, and `conda`.
+    - Profiles for the management of software using software management tools, e.g., `docker`, `singularity`, and `conda`
 - **Test profiles**
-    - Profiles to execute the workflow with a standardized set of test data and parameters, e.g., `test` and `test_full`.
-    - Test profiles are typically used during development to check whether new changes work as expected. They are also a great place to start when learning how to use a new pipeline.
+    - Profiles to execute the workflow with a standardized set of test data and parameters, e.g., `test` and `test_full`
+    - Test profiles are typically used during development to check whether new changes work as expected; they are also a great place to start when learning how to use a new pipeline
 
 Multiple profiles can be specified in a comma-separated (`,`) list when you execute your command. The order of profiles is important as they will be read from left to right. If there is any overlap in the configuration options set by each profile, the right-most profile will take precedence.
 
@@ -168,9 +159,17 @@ nextflow run <workflow> -profile test,singularity
 
         ```
 
-## 1.3.2 Viewing parameters
+## 1.3.2 Workflow parameters
+
+Every nf-core workflow defines a set of workflow parameters that can be used to pass data, filtering thresholds, options, and other information to the pipeline and influence how it runs. These parameters are defined and given sensible defaults in the main `nextflow.config` file in the pipeline repository. While these default values are chosen to be applicable to the average user, you will almost certainly want to modify some of these to fit your own purposes and datasets.
 
-Every nf-core workflow has an associated **schema** which describes the full list of **parameters** it accepts. You can find this manifest on the pipeline's page on the nf-core website, which displays a description and value type of each parameter. Most parameters will have additional text to help you understand when and how a parameter should be used. For example, the following is from the parameter page for `nf-core/rnaseq`:
+!!! warning "IMPORTANT!"
+
+    nf-core workflow **parameters** must be passed via the command line (`--<parameter>`) or Nextflow `-params-file` option. Custom config files, including those provided by the `-c` option, can be used to provide any configuration **except** for parameters.
+
+    We discuss both of these methods for passing parameters further down.
+
+To help with setting parameters, each nf-core pipeline has an associated **schema** which describes the full list of **parameters** it accepts. You can find this manifest on the pipeline's page on the nf-core website, which displays a description and value type of each parameter. Most parameters will have additional text to help you understand when and how a parameter should be used. For example, the following is from the parameter page for `nf-core/rnaseq`:
 
 [![](../assets/1.3_params.excalidraw.png){width=80%}](https://nf-co.re/rnaseq/3.23.0/parameters)
 
@@ -254,6 +253,8 @@ At the highest level, parameters can be customized using the command line. Any p
 nextflow run <workflow> --<parameter>
 ```
 
+Parameters set via the command line this way take the highest precedence and will override conflicting parameters defined in any `-params-file` or in the default configuration.
+
 !!! tip
 
     Remember that workflow parameters are prefixed with a **double dash** (`--`), while options to the `nextflow run` command itself are prefixed with a single dash (`-`).
@@ -342,28 +343,28 @@ All parameters will have a default setting that is defined using the `nextflow.c
 There are also several `includeConfig` statements in the `nextflow.config` file that are used to include additional `.config` files from the `conf/` folder. Each additional `.config` file contains categorized configuration information for your workflow execution, some of which can be optionally included:
 
 - `base.config`
-    - Included by the workflow by default.
-    - Generous resource allocations using labels.
-    - Does not specify any method for software management and expects software to be available (or specified elsewhere).
+    - Included by the workflow by default
+    - Generous resource allocations using labels
+    - Does not specify any method for software management and expects software to be available (or specified elsewhere)
 - `igenomes.config`
-    - Included by the workflow by default.
-    - Default configuration to access reference files stored on [AWS iGenomes](https://ewels.github.io/AWS-iGenomes/).
+    - Included by the workflow by default
+    - Default configuration to access reference files stored on [AWS iGenomes](https://ewels.github.io/AWS-iGenomes/)
     - Note that the iGenomes reference data may be out of date, so use with caution!
 - `modules.config`
-    - Included by the workflow by default.
-    - Module-specific configuration options (both mandatory and optional).
+    - Included by the workflow by default
+    - Module-specific configuration options (both mandatory and optional)
 - `test.config`
-    - Only included if specified as a profile.
-    - A configuration profile to test the workflow with a small test dataset.
+    - Only included if specified as a profile
+    - A configuration profile to test the workflow with a small test dataset
 - `test_full.config`
-    - Only included if specified as a profile.
-    - A configuration profile to test the workflow with a full-size test dataset.
+    - Only included if specified as a profile
+    - A configuration profile to test the workflow with a full-size test dataset
 
 nf-core workflows are required to define **software containers** and **conda environments** that can be activated using profiles. Although it is possible to run the workflows with software installed by other methods (e.g., environment modules or manual installation), using containerisation systems like Docker or Singularity is more convenient and more reproducible.
 
 !!! tip
 
-    If you're computer has internet access and one of Conda, Singularity, or Docker installed, you should be able to run any nf-core workflow with the `test` profile and the respective software management profile 'out of the box'. The `test` data profile will pull small test files directly from the `nf-core/test-data` GitHub repository and run it on your local system. The `test` profile is an important control to check the workflow is working as expected and is a great way to trial a workflow. Some workflows have multiple test `profiles` for you to test.
+    If you're computer has internet access and one of Conda, Singularity, or Docker installed, you should be able to run any nf-core workflow with the `test` profile and the respective software management profile 'out of the box'. The `test` data profile will pull small test files directly from the `nf-core/test-data` GitHub repository and run it on your local system. The `test` profile is an important control to check the workflow is working as expected and is a great way to trial a workflow. Some workflows have multiple test profiles for you to trial.
 
 ## 1.3.5 Shared configuration files
 
@@ -409,7 +410,7 @@ nextflow run <workflow> -profile test,docker -params-file /path/to/custom_params
 
 !!! example "Exercise 1.3.6.1"
 
-    Run the `nf-core-demo` pipeline again and use a custom parameter file to set the title of the MultiQC report to the name of your **favourite food**.
+    Run the `nf-core-demo` pipeline again and use a custom **parameter file** to set the title of the MultiQC report to the name of your **favourite food**.
 
     ??? success "Solution"
 
@@ -450,24 +451,24 @@ This allows you to customise the configuration of the Nextflow run beyond the de
 Custom configuration files follow the same structure as the configuration file included in the workflow directory. Configuration properties are organized into [scopes](https://docs.seqera.io/nextflow/config#syntax) by dot-prefixing the property names with a scope identifier or grouping the properties in the same scope using the curly brackets notation. For example:
 
 ```groovy
-alpha.x  = 1
-alpha.y  = 'string value..'
+process.cpus  = 1
+process.memory  = '4 GB'
 ```
 
 Is equivalent to:
 
 ```groovy
-alpha {
-     x = 1
-     y = 'string value..'
+process {
+    cpus = 1
+    memory = 'string value..'
 }
 ```
 
 Scopes allow you to quickly configure settings required to deploy a workflow on different infrastructure using different software management. For example, the `executor` scope can be used to provide settings for the deployment of a workflow on a HPC cluster. Similarly, the `singularity` scope controls how Singularity containers are executed by Nextflow. Multiple scopes can be included in the same `.config` file using a mix of dot prefixes and curly brackets. See the [Nextflow documentation](https://docs.seqera.io/nextflow/config) for more information on writing configuration files, as well as [this list of configuration options](https://docs.seqera.io/nextflow/reference/config).
 
 !!! example "Exercise 1.3.6.2"
 
-    Run the `nf-core-demo` pipeline again and use a custom config file to set the title of the MultiQC report to the name of your **favourite colour**.
+    Run the `nf-core-demo` pipeline again and use a custom **config file** to set the title of the MultiQC report to the name of your **favourite colour**.
 
     ??? success "Solution"
 
@@ -536,7 +537,7 @@ Scopes allow you to quickly configure settings required to deploy a workflow on
 
         !!! warning "Why did this fail?"
 
-            When using nf-core pipelines, you **can not** use the `params` scope in custom configuration files. Parameters can **only** be configured using either a parameter file and the `-params-file` option, or using the `--<parameter_name>` syntax directly on the command line.
+            When using nf-core pipelines, you **cannot** use the `params` scope in custom configuration files. Parameters can **only** be configured using either a parameter file and the `-params-file` option, or using the `--<parameter_name>` syntax directly on the command line.
 
 !!! example "Exercise 1.3.6.3"
 
@@ -590,7 +591,7 @@ process {
 
 !!! tip
 
-    Note that `withName` selectors take precedence over `withLabel` selector. In the above example, if the process `MYPROCESS` also had the label `BIG_JOB`, it would only be assigned 4 CPUs and 8GB of memory as per the `withName` configuration.
+    Note that `withName` selectors take precedence over `withLabel` selector. In the above example, if the process `MYPROCESS` also had the label `BIG_JOB`, it would only be assigned 4 CPUs and 8 GB of memory as per the `withName` configuration.
 
 Most tools have lots of parameters that can be set on the command line. A workflow might expose the most important and frequently used of these as *workflow parameters* that can be directly configured via the `--<parameter_name>` syntax or in a parameter file.
 
@@ -784,7 +785,7 @@ profiles {
 
 !!! note "Key points"
 
-    - nf-core workflows follow a similar structure.
-    - nf-core workflows are configured using multiple configuration sources.
-    - Configuration sources are ranked to decide which settings to apply.
-    - Workflow parameters must be passed via the command line (`--<parameter>`) or Nextflow `-params-file` option.
+    - nf-core workflows follow a similar structure
+    - nf-core workflows are configured using multiple configuration sources
+    - Configuration sources are ranked to decide which settings to apply
+    - Workflow parameters must be passed via the command line (`--<parameter>`) or Nextflow `-params-file` option