# Quick Start

# Quick Start for gimap

For more background on gimap and the calculations done here, read here

## Requirements

Besides installing the gimap package, you will also need to install wget if you do not already have it installed. This will allow you to download the annotation files needed to run `gimap`.

How to install wget

## Data download requirements

Example data are hosted on Figshare and are not bundled with the package to keep the CRAN tarball small. `get_example_data()` will download the files on first use to a user data directory. For manual download instructions, see the README section “Manual data download (Figshare)”.

To install the `gimap` package you will need to run:

    install.packages("gimap")

Or you can install the development version from GitHub:

    install.packages("remotes")
    remotes::install_github("FredHutch/gimap")

## Loading needed packages

    #>
    #> Attaching package: 'dplyr'
    #> The following objects are masked from 'package:stats':
    #>
    #>     filter, lag
    #> The following objects are masked from 'package:base':
    #>
    #>     intersect, setdiff, setequal, union

## Set Up

First we can create a folder we will save files to.

    output_dir <- "output_timepoints"
    dir.create(output_dir, showWarnings = FALSE)

    example_data <- get_example_data("count")

## Setting up data

We’re going to set up three datasets that we will provide to the `set_up()` function to create a `gimap` dataset object.

- `counts` - the counts generated from pgPEN
- `pg_ids` - the IDs that correspond to the rows of the counts and specify the construct
- `sample_metadata` - metadata that describes the columns of the counts including their timepoints

    counts <- example_data %>%
      select(c("Day00_RepA", "Day22_RepA", "Day22_RepB", "Day22_RepC")) %>%
      as.matrix()

`pg_id` are just the unique IDs listed in the same order/sorted the same way as the count data.

    pg_ids <- example_data %>%
      dplyr::select("id")

Sample metadata is the information that describes the samples and is sorted the same order as the columns in the count data.

    sample_metadata <- data.frame(
      col_names = c("Day00_RepA", "Day22_RepA", "Day22_RepB", "Day22_RepC"),
      day = as.numeric(c("0", "22", "22", "22")),
      rep = as.factor(c("RepA", "RepA", "RepB", "RepC"))
    )

We’ll need to provide `example_counts`, `pg_ids` and `sample_metadata` to `setup_data()`.

    gimap_dataset <- setup_data(
      counts = counts,
      pg_ids = pg_ids,
      sample_metadata = sample_metadata
    )

It’s ideal to run quality checks first. The `run_qc()` function will create a report we can look at to assess this.

    run_qc(gimap_dataset,
      output_file = file.path(output_dir, "example_qc_report.Rmd"),
      overwrite = TRUE,
      plots_dir = "plots",
      quiet = TRUE
    )

You can take a look at an example QC report here.

    gimap_dataset <- gimap_dataset %>%
      gimap_filter() %>%
      gimap_annotate(cell_line = "HELA") %>%
      gimap_normalize(
        timepoints = "day"
      ) %>%
      calc_gi()

## Example output

Genetic interaction is calculated by:

- `pgRNA_target` - what gene(s) were targeted by this the original pgRNAs for these data
- `mean_expected_cs` - the average expected genetic interaction score
- `mean_gi_score` - the average observer genetic interaction score
- `target_type` - describes whether the CRISPR design is targeting two genes (“gene_gene”), or a gene and a non targeting control (“gene_ctrl”) or a targeting control and a gene (“ctrl_gene”).
- `p_val` - p values from the testing whether a double knockout construct is significantly different in its genetic interaction score from single targets.
- `fdr` - False discovery rate corrected p values

    gimap_dataset$gi_scores %>%
      dplyr::arrange(fdr) %>%
      head() %>%
      knitr::kable(format = "html")

## Plot the results

You can remove any samples from these plots by altering the `reps_to_drop` argument.

    plot_exp_v_obs_scatter(gimap_dataset)

    # Save it to a file
    ggsave(file.path(output_dir, "exp_v_obs_scatter.png"))

    plot_rank_scatter(gimap_dataset)

    # Save it to a file
    ggsave(file.path(output_dir, "plot_rank_scatter.png"))

    plot_volcano(gimap_dataset)

    # Save it to a file
    ggsave(file.path(output_dir, "volcano_plot.png"))

### Plot specific target pair

We can pick out a specific pair to plot.

    # "CNOT8_CNOT7" is top result so let's plot that
    plot_targets(gimap_dataset, target1 = "CNOT8", target2 = "CNOT7")

    # Save it to a file
    ggsave(file.path(output_dir, "CNOT8_CNOT7.png"))

## Saving data to a file

We can save all these data as an RDS or the genetic interaction scores themselves to a tsv file.

    saveRDS(gimap_dataset, "gimap_dataset_final.RDS")

    readr::write_tsv(gimap_dataset$gi_scores, "gi_scores.tsv")

## Session Info

This is just for provenance purposes.

    sessionInfo()
    #> R version 4.5.0 (2025-04-11)
    #> Platform: aarch64-apple-darwin20
    #> Running under: macOS Sequoia 15.7.3
    #>
    #> Matrix products: default
    #> BLAS:   /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRblas.0.dylib
    #> LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    #>
    #> locale:
    #> [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    #>
    #> time zone: America/New_York
    #> tzcode source: internal
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> other attached packages:
    #> [1] dplyr_1.1.4 gimap_1.1.2
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] gtable_0.3.6       jsonlite_2.0.0     compiler_4.5.0     tidyselect_1.2.1
    #>  [5] stringr_1.5.1      snakecase_0.11.1   tidyr_1.3.1        jquerylib_0.1.4
    #>  [9] scales_1.4.0       yaml_2.3.10        fastmap_1.2.0      ggplot2_3.5.2
    #> [13] R6_2.6.1           generics_0.1.4     knitr_1.50         tibble_3.2.1
    #> [17] janitor_2.2.1      openssl_2.3.2      lubridate_1.9.4    bslib_0.9.0
    #> [21] pillar_1.10.2      RColorBrewer_1.1-3 rlang_1.1.6        cachem_1.1.0
    #> [25] stringi_1.8.7      xfun_0.52          sass_0.4.10        timechange_0.3.0
    #> [29] cli_3.6.5          magrittr_2.0.3     digest_0.6.37      grid_4.5.0
    #> [33] rstudioapi_0.17.1  askpass_1.2.1      lifecycle_1.0.4    vctrs_0.6.5
    #> [37] pheatmap_1.0.13    evaluate_1.0.3     glue_1.8.0         farver_2.1.2
    #> [41] purrr_1.0.4        rmarkdown_2.29     httr_1.4.7         tools_4.5.0
    #> [45] pkgconfig_2.0.3    htmltools_0.5.8.1