Uniformise key parameters

[rcannood]

Examples of what we currently have:

• --modality: Which modality to use (ok)
• --layer: Which layer to use (ok)
• --obs_filter:
• --var_filter:
• --obs_name_filter: Which obs column to filter with
• --var_name_filter: Which var column to filter with
• --pca_key:
• --output_key:

Except for --modality and --layer, what notation should we use for allowing the user to choose the key for input/output data?

[rcannood]

Option 1 --<name>_name: Description of what the argument does

• filter/do_filter: inputs --obs_name and --var_name
• integrate/harmony: inputs --embedding_name and --covariates_name, outputs --output_embedding_name
• cluster/leiden: outputs --cluster_name

Option 2 --<data structure>_field: Describe where it is stored (similar to scanpy/harmony_integrate.py#L49

• filter/do_filter: inputs --obs_field and --var_filter_field
• integrate/harmony: inputs --obsm_field and --obs_field, outputs --obsm_field
• cluster/leiden: outputs --obs_field

Option 3 --<data structure>_<name>_field: Why not both

• filter/do_filter: inputs --obs_filter_field and --var_filter_field
• integrate/harmony: inputs --obsm_embedding_field and --obs_covariates_field, outputs --obsm_output_field
• cluster/leiden: outputs --obs_output_field

Option 4 --<data structure>_<name>: Same but without the _field

• filter/do_filter: inputs --obs_filter and --var_filter
• integrate/harmony: inputs --obsm_embedding and --obs_covariates, outputs --obsm_output
• cluster/leiden: outputs --obs_output

Option 5 --<data structure>_<input/output/name>: Use input / output when it is clear what is being meant, use alternative names when further explanation is needed

• filter/do_filter: inputs --obs_input and --var_input
• integrate/harmony: inputs --obsm_input and --obs_covariates, outputs --obsm_output
• cluster/leiden: outputs --obs_output

---

Option 1:

• Pro: The user is being told what the argument is used for (e.g. as a covariate)

Option 2:

• Pro: Naming is more predictable
• Pro: User is being told where the data should be stored (e.g. in an obsm field)
• Con: Possible name clashes when components have multiple input fields (e.g. --obsm_field and --obsm_field)

Option 3:

• Pro: The user is being told what the argument is used for (e.g. as a covariate)
• Pro: User is being told where the data is stored (e.g. in an obsm field)
• Con: Can be a hassle

Option 4:

• Same benefits as option 3

Option 5:

• Con: Ambiguous

Variants 1:

• Use `_name
• Use *_key
• Use *_field
• Use *_name for .obs and .var, _key for .obsm, .varm, .obsp, ...

Variants 2:

• --obs_output
• --output_obs

---

Sugar syntax: Allow hashmaps as parameters.

• filter/do_filter: --format '{"obs_filter": "foo", "var_filter": "bar"}'
• integrate/harmony: --format '{"obsm_embedding": "X_pca", "obs_covariates": [ "sample", "batch" ], "obsm_output": "X_pca_harmony"}'
• cluster/leiden: --format '{"obs_output": "foo"}'

[rcannood]

Decision: we'll use option 4 To do: reformat the components to be consistent with this decision :)

[rcannood]

This was tackled in release 0.5.0!