---
title: "createParam V1" 
editor_options: 
  chunk_output_type: console
type: docs
weight: 3
---

```{r setup, echo=TRUE, message=FALSE, warning=FALSE}
suppressPackageStartupMessages({
    library(systemPipeR)
})
```

`createParam` by default uses the version 1 syntax, so there is no need to 
provide additional version argument. We will see in the [next section](../create_param_v2) how to 
use `syntaxVersion` to change to the v2 syntax.


## Input

Imagine we want to create CWL for command: 

```{bash, eval=FALSE}
hisat2 -S ./results/M1A.sam -x ./data/tair10.fasta -k 1 -min-intronlen 30 -max-intronlen 3000 -threads 4 -U ./data/SRR446027_1.fastq.gz
```

To use `createParam`, simply write the command in a pseudo-bash script format:

```{r cmd, eval=TRUE}
command <- "
    hisat2 \
    -S <F, out: ./results/M1A.sam> \
    -x <F: ./data/tair10.fasta> \
     -k <int: 1> \
    -min-intronlen <int: 30> \
    -max-intronlen <int: 3000> \
    -threads <int: 4> \
    -U <F: ./data/SRR446027_1.fastq.gz>
"
```

### Format

What does the string above mean?

- First line is the base command. Each line is an argument with its default value.

- For argument lines (starting from the second line), any word before the first 
  space with leading `-` or `--` in each will be treated as a prefix, like `-S` or 
  `--min`. Any line without this first word will be treated as no prefix. 
  
- All defaults are placed inside `<...>`.

- First argument is the input argument type. "File" (or "F") for files, "int" for integers, "string" for character strings.

- Optional: use the keyword `out` followed the type with a `,` comma separation to 
  indicate if this argument is also an CWL output.
  
- Then, use `:` to separate keywords and default values, any non-space value after the `:`
  will be treated as the default value. 
  
- If any argument has no default value, just a flag, like `--verbose`, there is no need to add any `<...>`

## run `createParam` Function

The string above that we just defined will be used as input for `createParam`. 

If the format is correct, after parsing, the function will print the three components of the `cwl` file:
    - `BaseCommand`: Specifies the program to execute. 
    - `Inputs`: Defines the input parameters of the process.
    - `Outputs`: Defines the parameters representing the output of the process.
    
The fourth printed component is the translated command-line from CWL.

If in you are using R interactively, the function will verify that everything is correct and 
will ask you to proceed. Here, the user can answer "no" and provide more 
information at the string level. Another question is to save the param created here.

If running the workflow in non-interactive mode, the `createParam` function will 
consider "yes" and returning the container.

```{r}
cmd <- createParam(command, writeParamFiles = FALSE)
```

If the user chooses not to save the `param` files on the above operation, 
later, one can use the `writeParamFiles` function.

```{r saving}
writeParamFiles(cmd, overwrite = TRUE)
```

By default, the files will be saved inside `./param/cwl/base_cmd`. It means a 
child folder under _param_ then _cwl_, and create a new folder named by the base command
of the command-line. 

## Access and edit param files

### Print a component

```{r}
printParam(cmd, position = "baseCommand") ## Print a baseCommand section
printParam(cmd, position = "outputs")
printParam(cmd, position = "inputs", index = 1:2) ## Print by index
printParam(cmd, position = "inputs", index = -1:-2) ## Negative indexing printing to exclude certain indices in a position
```

### Subsetting the command-line

```{r}
cmd2 <- subsetParam(cmd, position = "inputs", index = 1:2, trim = TRUE)
cmdlist(cmd2)

cmd2 <- subsetParam(cmd, position = "inputs", index = c("S", "x"), trim = TRUE)
cmdlist(cmd2)
```

### Replacing a existing argument in the command-line

```{r}
cmd3 <- replaceParam(cmd, "base", index = 1, replace = list(baseCommand = "bwa"))
cmdlist(cmd3)
```

```{r}
new_inputs <- new_inputs <- list(
    "new_input1" = list(type = "File", preF="-b", yml ="myfile"),
    "new_input2" = "-L <int: 4>"
)
cmd4 <- replaceParam(cmd, "inputs", index = 1:2, replace = new_inputs)
cmdlist(cmd4)
```

### Adding new arguments

```{r}
newIn <- new_inputs <- list(
    "new_input1" = list(type = "File", preF="-b1", yml ="myfile1"),
    "new_input2" = list(type = "File", preF="-b2", yml ="myfile2"),
    "new_input3" = "-b3 <F: myfile3>"
)
cmd5 <- appendParam(cmd, "inputs", index = 1:2, append = new_inputs)
cmdlist(cmd5)

cmd6 <- appendParam(cmd, "inputs", index = 1:2, after=0, append = new_inputs)
cmdlist(cmd6)
```

### Editing `output` param

```{r}
new_outs <- list(
    "sam_out" = "<F: $(inputs.results_path)/test.sam>"
) 
cmd7 <- replaceParam(cmd, "outputs", index = 1, replace = new_outs)
output(cmd7) 
```