update doc links, add missing readme files for bean run

docs/_tutorial_cds.md

@@ -83,7 +83,7 @@ bean profile ${working_dir}/${screen_id}.h5ad --pam-col '5-nt PAM'
 Check the editing window, and consider feeding the start/end position of the editing window with the maximal editing rate into `bean qc` with `--edit-start-pos`, `--edit-end-pos` arguments.  
 
 ### Output
-Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main/bean/docs/example_profile_output/).
+Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main/bean/docs/example_profile_output/).
 
 
 ## 2. QC (:ref:`qc`)
@@ -100,7 +100,7 @@ bean qc \
 If the data does not include reporter editing data, you can provide `--no-editing` flag to omit the editing rate QC.  
 
 ### Output
-Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main/bean/docs/example_profile_output/).
+Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main/bean/docs/example_qc_output/).
 
 ## 3. Filter alleles (:ref:`filter`)
 As tiling library doesn't have designated per-gRNA target variant, any base edit observed in reporter may be the candidate variant, while having too many variants with very low editing rate significantly decreases the power. Variants are filtered based on multiple criteria in `bean fitler`.  

docs/_tutorial_gwas.md

@@ -75,8 +75,7 @@ bean profile tests/data/${screen_id}.h5ad --pam-col '5-nt PAM'
 ```
 
 ### Output
-Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main/docs/example_profile_output).
-
+Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main/docs/example_profile_output).
 
 ## 2. QC samples & guides (:ref:`qc`)
 Base editing data will include QC about editing efficiency. As QC uses predefined column names and values, beware to follow the [input file guideline](https://pinellolab.github.io/crispr-bean/input.html), but you can change the parameters with the full argument list of [bean qc](https://pinellolab.github.io/crispr-bean/qc.html). (Common factors you may want to tweak is `--ctrl-cond=bulk` and `--lfc-conds=top,bot` if you have different sample condition labels.)
@@ -92,7 +91,7 @@ bean qc \
 If the data does not include reporter editing data, you can provide `--no-editing` flag to omit the editing rate QC.
 
 ### Output
-Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main/docs/example_profile_output).
+Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main/docs/example_qc_output).
 
 
 ## 3. Quantify variant effect (:ref:`run`)

docs/_tutorial_prolif_cds.md

@@ -97,7 +97,7 @@ bean profile tests/data/${screen_id}.h5ad --pam-col '5-nt PAM'
 Check the editing window, and consider feeding the start/end position of the editing window with the maximal editing rate into `bean qc` with `--edit-start-pos`, `--edit-end-pos` arguments.
 
 ### Output
-Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main//docs/example_profile_output/).
+Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main//docs/example_profile_output/).
 
 ## 2. QC (:ref:`qc`)
 Base editing data will include QC about editing efficiency. As QC uses predefined column names and values, beware to follow the [input file guideline](https://pinellolab.github.io/crispr-bean/input.html), but you can change the parameters with the full argument list of [bean qc](https://pinellolab.github.io/crispr-bean/qc.html). (Common factors you may want to tweak is `--ctrl-cond=bulk` and `--lfc-conds=top,bot` if you have different sample condition labels.)
@@ -113,7 +113,7 @@ bean qc \
 If the data does not include reporter editing data, you can provide `--no-editing` flag to omit the editing rate QC.
 
 ### Output
-Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main//docs/example_profile_output/).
+Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main//docs/example_qc_output/).
 
 ## 3. Filter alleles (:ref:`filter`)
 As tiling library doesn't have designated per-gRNA target variant, any base edit observed in reporter may be the candidate variant, while having too many variants with very low editing rate significantly decreases the power. Variants are filtered based on multiple criteria in `bean fitler`.  

docs/_tutorial_prolif_gwas.md

@@ -85,7 +85,7 @@ bean profile tests/data/${screen_id}.h5ad --pam-col '5-nt PAM'
 ```
 
 ### Output
-Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main//docs/example_profile_output/).
+Output will be written under `${working_dir}/bean_profile.${screen_id}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main/docs/example_profile_output/).
 
 ## 2. QC samples & guides (:ref:`qc`)
 Base editing data will include QC about editing efficiency. As QC uses predefined column names and values, beware to follow the [input file guideline](https://pinellolab.github.io/crispr-bean/input.html), but you can change the parameters with the full argument list of [bean qc](https://pinellolab.github.io/crispr-bean/qc.html). (Common factors you may want to tweak is `--ctrl-cond=bulk` and `--lfc-conds=top,bot` if you have different sample condition labels.)
@@ -102,7 +102,7 @@ bean qc \
 If the data does not include reporter editing data, you can provide `--no-editing` flag to omit the editing rate QC.
 
 ### Output
-Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/blob/main//docs/example_profile_output/).
+Output will be written under `${working_dir}/`. See example output [here](https://github.com/pinellolab/crispr-bean/tree/main//docs/example_qc_output/).
 
 ## 3. Quantify variant effect (:ref:`run`)
 

docs/example_run_output/tiling/README.md

@@ -0,0 +1,31 @@
+# `bean run` output files
+These are the example output of [`bean run`](https://pinellolab.github.io/crispr-bean/run.html).
+`bean run` produces [`bean_element_result.[model_type].csv`] as the main output and will produce log and per-guide information files, and intermediate `.pkl` file that saves ELBO loss for variational inference.
+
+## `bean_element_result.[model_type].csv`
+- Variant ID / grouping
+  - `edit`: Variant ID.
+  - `group`: The grouping of the coding variants, assigned as one of nonsense/missense/synonymous.
+  - `int_pos`: The integer position of the noncoding variants.
+  - `chrom`: The chromosome of the variant.
+  - `pos`: The position of the variant. If coding variant, starts with `A` and the position specified 1-based amino acid position. If noncodig variant, numeric genomic position.
+  - `ref`: The reference base/amino acid of the variant.
+  - `alt`: The alternative base/amino acid of the variant.
+  - `coding`: A flag indicating if the element is coding variant or not.
+
+- Per-variant summary of variant-producing guides
+  - `guide_target_group`: Aggregated `target_group` column in the input sgRNA_info.csv file. All unique values of the guides that produced (filtered) edited alleles that includes this variant is listed.
+  - `effective_edit_rate`: The effective editing rate of the element. Calculated as `sum_over_guides(sum_over_alleles(per_guide_allele_editing_rate / # variants in the allele))`.
+  - `editing_guides`: List of guides that edited the variant.
+  - `per_guide_editing_rates`: The per-guide editing rates of the variant.
+  - `n_guides`: The number of guides that edited the variant.
+  - `n_coocc`: The number of unique co-occurring variants that appeared together in any alleles that contains the variant.
+- Variant effect size: Use `mu_z_adj` whenever available, otherwise `mu_z_scaled`, otherwise `mu_z`.
+  - `mu`: The mean value of the variant effect size.
+  - `mu_sd`: The standard deviation of the mean value of the variant effect size.
+  - `mu_z`: The z-score of the mean value of the variant effect size.
+  - `sd`: The standard deviation of the phenotype induced by the variant.
+  - `CI[0.025,0.975]`: The 95% credible interval of the mean value of the variant effect size. Corresponds to `mu_z_adj` when available, otherwise `mu_z_scaled`, otherwise `mu_z`. 
+  - `[]_scaled`: Above values scaled by negative control variants.
+  - `[]_adj`: Above values scaled by synonymous variants.
+

docs/example_run_output/variant/README.md

@@ -0,0 +1,20 @@
+# `bean run` output files
+These are the example output of [`bean run`](https://pinellolab.github.io/crispr-bean/run.html).
+`bean run` produces [`bean_element_result.[model_type].csv`] as the main output and will produce log and per-guide information files, and intermediate `.pkl` file that saves ELBO loss for variational inference.
+
+## `bean_element_result.[model_type].csv`
+- Variant ID / grouping
+  - `target`: Target variant / element.
+  - `target_group`: The group of the target variant / element, as specified in the input.
+- Per-variant summary of variant-producing guides
+  - `n_guides`: The number of guides targeting the variant, as described in the input.
+  - `edit_rate_mean`: The mean editing rate of the variant.
+  - `edit_rate_std`: The standard deviation of the editing rate of the variant.
+- Variant effect size: Use `mu_z_adj` whenever available, otherwise `mu_z_scaled`, otherwise `mu_z`.
+  - `mu`: The mean value of the variant effect size.
+  - `mu_sd`: The standard deviation of the mean value of the variant effect size.
+  - `mu_z`: The z-score of the mean value of the variant effect size.
+  - `sd`: The standard deviation of the phenotype induced by the variant.
+  - `CI[0.025,0.975]`: The 95% credible interval of the mean value of the variant effect size. Corresponds to `mu_z_adj` when available, otherwise `mu_z_scaled`, otherwise `mu_z`. 
+  - `[]_scaled`: Above values scaled by negative control variants.
+  - `[]_adj`: Above values scaled by negative control variants.