Merge pull request #16 from shntnu/docs

Document how to use local files

Author: shntnu

matric/README.md

@@ -24,7 +24,6 @@ The docker image has all the dependencies installed and the `evalzoo` repo clone
 `~/Desktop/input` is the folder where your input data is stored.
 In the container, this is mapped to `/input`.
 You can change this to any folder on your computer.
-The example below does not need any input data.
 
 Open <http://localhost:8787/> in your browser and log in using the crendentials `rstudio` / `rstudio`.
 
@@ -43,22 +42,47 @@ run_param("params/params_cellhealth.yaml")
 Knitted notebooks and outputs, including metrics, are written to a configuration-specific subfolder of `results/`.
 See `5.inspect-metrics` for how to access them.
 
-### Optionally change output location 
+The example parameter file `params/params_cellhealth.yaml` reads the input directly from a public GitHub repo.
 
-Use `results_root_dir` to specify the folder where you want the results to be stored. 
+Instead, your input might live on your local machine (and you might also want to store the results in some other folder).
 
-In the example below, we set it to `/input` which is the folder that we mapped to `~/Desktop/input` on the host machine when we started the docker container.
+In that case, the mapping (`~/Desktop/input:/input`) that you've set up in the docker command above will be useful.
+
+To mock this up, we'll use the same input file as in the example parameter file above.
+
+First download the file locally to `~/Desktop/input`:
+
+```bash
+mkdir -p ~/Desktop/input
+cd ~/Desktop/input
+url=https://github.com/broadinstitute/grit-benchmark/raw/main/1.calculate-metrics/cell-health/data/cell_health_merged_feature_select.csv.gz
+curl -L -o cell_health_merged_feature_select.csv.gz $url
+```
+
+Next, edit the parameter file `params/params_cellhealth.yaml` to point to the local file:
+
+```yaml
+  data_path: "/input"
+```
+
+and save it as `params/params_cellhealth_local.yaml` (the parameter file can live anywhere; it doesn't have to be in `params`)
+
+Then, run the following command in the R console:
 
 ```r
-run_param("params/params_cellhealth.yaml",  results_root_dir = "/input")
+setwd("matric")
+source("run_param.R")
+run_param("params/params_cellhealth_local.yaml",  results_root_dir = "/input")
 ```
 
+Here, we have additionally used `results_root_dir` to specify the folder where we want the results to be stored.
+
 TODO: Document the configuration file
 
 ## Addendum
 
 <details>
-  
+
 ### Notebooks
 
 - `1.prepare_data.Rmd` prepares the datasets.

matric/params/params_cellhealth.yaml

@@ -49,6 +49,8 @@ experiment:
       - Metadata_cell_line
       - Metadata_gene_name
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep:
       - Metadata_gene_name

matric/params/params_cellhealth_group.yaml

@@ -49,6 +49,8 @@ experiment:
     all_same_cols_rep:
       - Metadata_gene_name
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep: NULL
     all_same_cols_non_rep: NULL

matric/params/params_cellhealth_local.yaml

@@ -0,0 +1,67 @@
+knit_output_format: github_document
+experiment:
+  data_path: /input
+  input_structure: "{data_path}/cell_health_merged_feature_select.{extension}"
+  extension: csv.gz
+  external_metadata:
+  add_dummy_metadata_column: FALSE
+  split_by_column:
+  significance_threshold: 0.05
+  parallel_workers: 8
+  aggregate_by:
+    - Metadata_cell_line
+    - Metadata_gene_name
+    - Metadata_pert_name
+  filter_by:
+  reference_set:
+    Metadata_gene_name:
+      - Chr2
+      - Luc
+      - LacZ
+  random_seed: 42
+  background_type: non_rep
+  shuffle: FALSE
+  shuffle_bad_groups_threshold: 0.1
+  shuffle_group: Metadata_gene_name
+  shuffle_strata: NULL
+  shuffle_exclude:
+    Metadata_gene_name:
+      - Chr2
+      - Luc
+      - LacZ
+      - EMPTY
+  subsample_fraction: 1
+  subsample_pert_strata:
+    - Metadata_gene_name
+  subsample_reference_strata:
+    - Metadata_Well
+  similarity_method: cosine
+  sim_params:
+    drop_group:
+      Metadata_gene_name:
+        - EMPTY
+    reference:
+        Metadata_reference_or_other:
+          reference
+    all_same_cols_ref:
+      - Metadata_cell_line
+    all_same_cols_rep:
+      - Metadata_cell_line
+      - Metadata_gene_name
+      - Metadata_reference_or_other
+    # all_different_cols_rep:
+    # any_different_cols_rep:
+    all_same_cols_rep_ref: NULL
+    any_different_cols_non_rep:
+      - Metadata_gene_name
+    all_same_cols_non_rep:
+      - Metadata_cell_line
+    all_different_cols_non_rep:
+      - Metadata_gene_name
+    all_same_cols_group: NULL
+    any_different_cols_group: NULL
+    annotation_cols:
+      - Metadata_cell_line
+      - Metadata_pert_name
+      - Metadata_gene_name
+      - Metadata_reference_or_other

matric/params/params_cellhealth_shuffle.yaml

@@ -49,6 +49,8 @@ experiment:
       - Metadata_cell_line
       - Metadata_gene_name
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep:
       - Metadata_gene_name

matric/params/params_cpjump1_prod_biological_no_split.yaml

@@ -50,6 +50,8 @@ experiment:
     all_same_cols_rep:
       - Metadata_target_list
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep:
       - Metadata_target_list

matric/params/params_cpjump1_prod_biological_single_target.yaml

@@ -45,6 +45,8 @@ experiment:
     all_same_cols_rep:
       - Metadata_gene
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep:
       - Metadata_gene

matric/params/params_cpjump1_prod_biological_split.yaml

@@ -19,7 +19,7 @@ experiment:
   split_by_column:
     split_column: Metadata_target_list
     element_column: Metadata_broad_sample
-    compact_splits: FALSE  
+    compact_splits: FALSE
   significance_threshold: 0.05
   parallel_workers: 8
   aggregate_by:
@@ -53,6 +53,8 @@ experiment:
     all_same_cols_rep:
       - Metadata_target_list_split
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep:
       - Metadata_broad_sample

matric/params/params_cpjump1_prod_biological_split_compact.yaml

@@ -53,6 +53,8 @@ experiment:
     all_same_cols_rep:
       - Metadata_target_list_split_compact
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep:
       - Metadata_target_list_split_compact

matric/params/params_cpjump1_prod_biological_split_compact_no_filter.yaml

@@ -49,6 +49,8 @@ experiment:
     all_same_cols_rep:
       - Metadata_target_list_split_compact
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep:
       - Metadata_target_list_split_compact

matric/params/params_cpjump1_prod_technical.yaml

@@ -46,6 +46,8 @@ experiment:
       - Metadata_broad_sample
       - Metadata_control_type
       - Metadata_reference_or_other
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref: NULL
     any_different_cols_non_rep: NULL
     all_same_cols_non_rep: NULL

matric/params/params_luad.yaml

@@ -33,6 +33,8 @@ experiment:
       - Metadata_cell_line
       - Metadata_pert_name
       - Metadata_gene_name
+    all_different_cols_rep:
+    any_different_cols_rep:
     all_same_cols_rep_ref:
     any_different_cols_non_rep:
       - Metadata_cell_line