spatial extension v1 (#9)

* spatial extension v1

* styler

* error correct

* spatial documentation

* fix tests

* add section about testing in CONTRIBUTING.md

* add spatial extention

---------

Co-authored-by: gorgitko <[email protected]>

.github/CONTRIBUTING.md

@@ -51,6 +51,48 @@ the team agrees that it's needed. If you've found a bug, please file an issue th
 - We use [testthat](https://cran.r-project.org/package=testthat) for unit tests.
   Contributions with test cases included are easier to accept.
 
+## Testing
+
+Important (but not all) parts of `scdrake` are covered by [testthat](https://testthat.r-lib.org/) unit tests.
+During the CI workflow, lighter of them are run automatically after the Docker image is built.
+
+Tests are heavily controlled by environment variables. Those are parsed in `tests/testthat/setup.R`
+and displayed on the beginning of testing. To ease the manipulation with envvars,
+there is a wrapper script `dev/run_tests.R`. It contains a CLI that transforms command line parameters
+to envvars used in tests. See `$ Rscript dev/run_tests.R` for the list of CLI parameters and
+at the same time, a list of envvars for tests.
+
+It's also possible to run tests from within your R session, using temporary envvars:
+
+```r
+devtools::load_all()
+withr::with_envvar(
+  c("SCDRAKE_TEST_RUN_PIPELINE_VIGNETTES = "TRUE""),
+  devtools::test(filter = "vignettes")
+)
+```
+
+### End-to-end (e2e) tests
+
+In case you make bigger changes, a fuller testing is very much recommended.
+This is covered by several end-to-end tests in `tests/testthat/test-run_pipeline.R` and
+`tests/testthat/test-run_pipeline_vignettes.R`.
+These tests are computationally demanding and cannot be run in the CI.
+
+The second thing is that even though e2e tests can succeed, there is no actual validation
+of their outputs. Thus, it's needed to manually inspect at least the produced reports.
+For this purpose, a persistent output directory can be set in `dev/run_tests.R`.
+
+You can use this short snippet to run e2e tests with preserved outputs:
+
+```bash
+docker exec -it -u rstudio -w /home/rstudio/scdrake <container_name> \
+  r --interactive -L /usr/local/lib/R/site-library -t dev/run_tests.R \
+  --no-test-single_sample-full-sct \
+  --output-dir /home/rstudio/shared/test_outputs \
+  --output-dir-pipeline-tests /home/rstudio/shared/test_outputs/pipeline_outputs
+```
+
 ## Code of Conduct
 
 Please note that the `{scdrake}` project is released with a

NAMESPACE

@@ -55,6 +55,7 @@ export(create_dummy_plot)
 export(create_img_link)
 export(create_integration_dirs)
 export(create_seu_for_heatmaps)
+export(create_signature_matrix_fn)
 export(create_single_sample_dirs)
 export(dimred_plots_cell_annotation_params_df_fn)
 export(dimred_plots_clustering_fn)
@@ -137,6 +138,7 @@ export(markers_plots_top)
 export(markers_table_files)
 export(md_header)
 export(merge_sce_metadata)
+export(meta_heatmap_ploting)
 export(na_empty)
 export(pca_phase_plots_fn)
 export(plotReducedDim_mod)
@@ -152,6 +154,7 @@ export(run_graph_based_clustering)
 export(run_integration)
 export(run_integration_r)
 export(run_kmeans_clustering)
+export(run_page_man_annotation)
 export(run_single_sample)
 export(run_single_sample_r)
 export(save_clustree)