Config file decisions

[gwaybio]

In #1 @axiomcura started the project off by adding the first snakemake DAG.

He writes:

Currently, the configuration file is present in the pull request but it is not useable due to requiring additional discussion in determining the structure of the config file and the setting of default parameters.

Let's use this discussion as a space to talk about these two topics (1. structure of config file; 2. default parameters)!

[axiomcura]

Definitely, sounds like a plan!

[gwaybio]

@axiomcura outlines a strategy to use kwargs in calls to pycytominer scripts here: #1 (comment)

[axiomcura]

Table of Contents

• Table of Contents
• Proposed Configfile Prototype
  • prototype 1: DAG based configuration
    • Pros an Cons
  • prototype 2: single file configuration
    • Pros and Cons
  • prototype 3: Module based configuration
    • Pros and Cons
  • prototype 4: Merge based approach
    • Pros and Cons

Proposed Configfile Prototype

prototype 1: DAG based configuration

This mainly focuses on that each dag has it's own configuration
and gets called from the main configurational file

Below is file structure:

├── config
│   ├── analysis_configs
│   │   └── aggregate_DAG.yaml
│   └── cytopipe_configs.yaml
├── rules
│   └── aggregate.smk
├── Snakefile
└── test.py

3 directories, 5 files

This will require to download a 3rd party dependency called pyyaml, which is a yaml parser that will be used, in this case, to read the aggregate_configs.yaml file.

In prototype1, the cytopipe_configs.yaml is only returning the aggregate_configs.yaml end-point path.

• NOTE: this example uses endpoints paths assuming that the config folder is in the same path level as the script

Therefore, inside the code, the absolute path or relative path is required to be assembled in runtime in order for pyyaml module to read it.

Pros an Cons

Pros:

• Settings focus on DAG, therefore the user know what types of analysis is occurring
• only handling python dictionary :D
• allows reusing same analysis class with different settings
  • example:
    • DAG1 and DAG2 use the same analysis class (SingleCell), however different parameters

Cons:

• scripts must assemble the absolute path to the desired .yaml file
• name indexing can be long when accessing very nested parameters
• required a dependency pyyaml
• reusing of class can be repetitive

prototype 2: single file configuration

Only uses on main configurational containing all the settings.

Using top level keywords to separate the specific configs

toplevel1:
    foo:
        foo1:
        foo2:
    bar:
        bar1:
        bar2:
toplevel2:
    analysis:
        module1:
            param1:
            param2:
        module2:
            param1:
            param2:

This is how the file structure look like:

├── config
│   └── cytopipe_configs.yaml
├── rules
│   └── aggregate.smk
├── Snakefile
└── test.py

2 directories, 4 files

Compared to prototype1, the analysis_config directory is removed

Pros and Cons

Pros:

• removes handling paths
• does not required the pyyaml dependency

Cons:

• not user friendly
  • can be difficult to read if more configurational parameters are added
  • can be difficult to change parameters
• user may have access to advance configurational files

prototype 3: Module based configuration

This is a more structure approach where each analysis has it's own yaml file.

file structure:

├── config
│   ├── analysis_confings
│   │   ├── annotate_config.yaml
│   │   ├── normalize_config.yaml
│   │   └── single_cell_config.yaml
│   └── cytopipe_configs.yaml
├── rules
│   └── aggregate.smk
├── Snakefile
└── test.py

3 directories, 7 files

Pros and Cons

Pros:

• Increases readability when comparing to both prototype1 and prototype2 in terms of using the same class in different

Cons:

• makes it difficult for reusability. (relatives in both parameters and files creation)
  • example: single_cell_config1.yaml single_cell_config2.yaml
• the more analysis modules are added, more .yaml files are required
• requires pyyaml dependency
• can be difficult to code
• can be difficult to navigate if user wants to access settings

NOTE: These issues can be solved with a script that is dedicated to only changing configurational files. Below is an example of a small program named cytopipe_configs.py. It requires the user to provide the name of the config file, parameter they want to change.

prototype 4: Merge based approach

Essentially is it prototype 1 and 2 (or 3) merged together (depending 2 or 3 depending on the file structure). Snakemake allows to use multiple configurational files by just adding multiple configurational files

# order matters! when name hashing "cytopipe_configs" will be the main name
configfile: "config/cytopipe_configs.yaml"
configfile: "config/analysis_configs/annotate_config.yaml"
configfile: "config/analysis_configs/single_cell_config.yaml"
configfile: "config/analysis_configs/normalize_config.yaml"

file structure shown below:

├── config
│   ├── analysis_confings
│   │   ├── annotate_config.yaml
│   │   ├── normalize_config.yaml
│   │   └── single_cell_config.yaml
│   └── cytopipe_configs.yaml
├── rules
│   └── aggregate.smk
├── Snakefile
└── test.py

3 directories, 7 files

Pros and Cons

pros:

• highly flexible when importing different configfile
• prevent stacking lots of parameters into one page
• flexibility for development
  • file structure
  • can be imported in Snakefile, or DAGS

cons

• may cause keyword collision and may alter parameters