Skip to contents

# Load a FlowJo workspace

Source: `vignettes/Load_a_FlowJo_workspace.Rmd`
`Load_a_FlowJo_workspace.Rmd`

    library(cyCONDOR)
    library(flowWorkspace)
    library(CytoML)
    library(Biobase)
    library(ggplot2)
    library(dplyr)

Within the `cyCONDOR` ecosystem it is possible to load a FlowJo work space (.wsp file). This gives the advantage of having the gating hierarchy in the `fcd` object. We would still reccomend using files preprocessed as described in vignette(“Prepare_data_for_cyCONDOR_analysis”) to be fully compatible with all downstream analysis (e.g. cytonorm). Exported compensared files can be loaded in FlowJo and used for gating analysis.

### Read the .wsp file

First we use the CytoML package to load the `.wsp` file.

    ws <- CytoML::open_flowjo_xml("../.test_files/flowjo_workspace.wsp")

    ws

    ## File location:  ../.test_files/flowjo_workspace.wsp
    ##
    ## Groups in Workspace
    ##          Name Num.Samples
    ## 1 All Samples           3
    ## 2     samples           3

### Transformation into GatingSet object

We then transform the object to a `GatingSet` object.

    gs <- CytoML::flowjo_to_gatingset(ws, name = "samples", path = "../.test_files/fcs_flowjo_ws/")

    gs

    ## A GatingSet with 3 samples

#### Visualization of the FlowJo gating strategy

We visualize the gating hierarchy and look at the cell count per gated population.

    flowWorkspace::plot(gs, bool = TRUE)

    flowWorkspace::gs_pop_get_stats(gs)

    ##                            sample
    ##                            <char>
    ##  1: Experiment_AID_01.fcs_1760146
    ##  2: Experiment_AID_01.fcs_1760146
    ##  3: Experiment_AID_01.fcs_1760146
    ##  4: Experiment_AID_01.fcs_1760146
    ##  5: Experiment_AID_01.fcs_1760146
    ##  6: Experiment_AID_01.fcs_1760146
    ##  7: Experiment_AID_01.fcs_1760146
    ##  8: Experiment_AID_01.fcs_1760146
    ##  9: Experiment_AID_01.fcs_1760146
    ## 10: Experiment_AID_02.fcs_3828740
    ## 11: Experiment_AID_02.fcs_3828740
    ## 12: Experiment_AID_02.fcs_3828740
    ## 13: Experiment_AID_02.fcs_3828740
    ## 14: Experiment_AID_02.fcs_3828740
    ## 15: Experiment_AID_02.fcs_3828740
    ## 16: Experiment_AID_02.fcs_3828740
    ## 17: Experiment_AID_02.fcs_3828740
    ## 18: Experiment_AID_02.fcs_3828740
    ## 19: Experiment_AID_03.fcs_4122432
    ## 20: Experiment_AID_03.fcs_4122432
    ## 21: Experiment_AID_03.fcs_4122432
    ## 22: Experiment_AID_03.fcs_4122432
    ## 23: Experiment_AID_03.fcs_4122432
    ## 24: Experiment_AID_03.fcs_4122432
    ## 25: Experiment_AID_03.fcs_4122432
    ## 26: Experiment_AID_03.fcs_4122432
    ## 27: Experiment_AID_03.fcs_4122432
    ##                            sample
    ##                                                              pop   count
    ##                                                           <char>   <num>
    ##  1:                                                         root 1760146
    ##  2:                                                 /Lymphocytes  259769
    ##  3:                                    /Lymphocytes/Single Cells  259132
    ##  4:                       /Lymphocytes/Single Cells/Single Cells  256701
    ##  5:                 /Lymphocytes/Single Cells/Single Cells/CD45+  243416
    ##  6:            /Lymphocytes/Single Cells/Single Cells/CD45+/CD3+   98595
    ##  7:           /Lymphocytes/Single Cells/Single Cells/CD45+/CD19+    6109
    ##  8:          /Lymphocytes/Single Cells/Single Cells/CD45+/others  138248
    ##  9: /Lymphocytes/Single Cells/Single Cells/CD45+/others/NK cells   15653
    ## 10:                                                         root 3828740
    ## 11:                                                 /Lymphocytes  502723
    ## 12:                                    /Lymphocytes/Single Cells  501266
    ## 13:                       /Lymphocytes/Single Cells/Single Cells  500119
    ## 14:                 /Lymphocytes/Single Cells/Single Cells/CD45+  478517
    ## 15:            /Lymphocytes/Single Cells/Single Cells/CD45+/CD3+  129406
    ## 16:           /Lymphocytes/Single Cells/Single Cells/CD45+/CD19+   15063
    ## 17:          /Lymphocytes/Single Cells/Single Cells/CD45+/others  333430
    ## 18: /Lymphocytes/Single Cells/Single Cells/CD45+/others/NK cells   14716
    ## 19:                                                         root 4122432
    ## 20:                                                 /Lymphocytes 1453126
    ## 21:                                    /Lymphocytes/Single Cells 1450633
    ## 22:                       /Lymphocytes/Single Cells/Single Cells 1440203
    ## 23:                 /Lymphocytes/Single Cells/Single Cells/CD45+ 1391893
    ## 24:            /Lymphocytes/Single Cells/Single Cells/CD45+/CD3+   92151
    ## 25:           /Lymphocytes/Single Cells/Single Cells/CD45+/CD19+   12424
    ## 26:          /Lymphocytes/Single Cells/Single Cells/CD45+/others 1286628
    ## 27: /Lymphocytes/Single Cells/Single Cells/CD45+/others/NK cells   22297
    ##                                                              pop   count

### Prepare the data for cyCONDOR

From the `GatingSet` object we prepare the `fcd` object using `prep_fjw()`. Here, we provide the `GatingSet` object as input, reverse the FlowJo tranformation, perform an autologicle transformation and remove the parameter “Time”. Optionally, we can read in an annotation table to add further sample information (not shown).

    condor <- prep_fjw(data_gs = gs,
                       inverse.transform = TRUE,
                       transformation = "auto_logi",
                       remove_param = c("Time")
                       )

    ## [1] "FSC-A w= 0 t= 262143"
    ## [1] "FSC-H w= 0 t= 166547"
    ## [1] "FSC-W w= 0 t= 262143"
    ## [1] "SSC-A w= 0.892977713264162 t= 262143"
    ## [1] "SSC-H w= 0 t= 257403"
    ## [1] "SSC-W w= 0 t= 262143"
    ## [1] "CD45 w= 0.400130442523775 t= 261330.171875"
    ## [1] "CD4 w= 0.583624943577614 t= 262054.046875"
    ## [1] "CD16 w= 0.583304445730326 t= 262063.21875"
    ## [1] "HLA-DR w= 0.526407100734133 t= 256403.078125"
    ## [1] "CD66b w= 0.269925173514296 t= 262130.15625"
    ## [1] "CD14 w= 0.520686238954203 t= 269475.84375"
    ## [1] "CD56 w= 0.309385967148849 t= 266870.46875"
    ## [1] "CD3 w= 0.777696607391664 t= 250297.484375"
    ## [1] "CD11c w= 0.537743667858708 t= 203113.46875"
    ## [1] "Siglec8 w= 0.323207654372646 t= 255847.03125"
    ## [1] "CD8 w= 0.654399836071111 t= 254885.03125"
    ## [1] "CD19 w= 0.343330229474141 t= 255034.515625"

    class(condor)

    ## [1] "flow_cytometry_dataframe"

The performed FlowJo gating with the assigned cell populations is saved in `condor$anno$cell_anno`.

    condor$anno$cell_anno[110:115,]

    ##                                 expfcs_filename root Lymphocytes
    ## Experiment_AID_01.fcs_110 Experiment_AID_01.fcs    1           0
    ## Experiment_AID_01.fcs_111 Experiment_AID_01.fcs    1           0
    ## Experiment_AID_01.fcs_112 Experiment_AID_01.fcs    1           0
    ## Experiment_AID_01.fcs_113 Experiment_AID_01.fcs    1           1
    ## Experiment_AID_01.fcs_114 Experiment_AID_01.fcs    1           0
    ## Experiment_AID_01.fcs_115 Experiment_AID_01.fcs    1           1
    ##                           Lymphocytes/Single Cells Single Cells/Single Cells
    ## Experiment_AID_01.fcs_110                        0                         0
    ## Experiment_AID_01.fcs_111                        0                         0
    ## Experiment_AID_01.fcs_112                        0                         0
    ## Experiment_AID_01.fcs_113                        1                         1
    ## Experiment_AID_01.fcs_114                        0                         0
    ## Experiment_AID_01.fcs_115                        1                         1
    ##                           CD45+ CD3+ CD19+ others NK cells
    ## Experiment_AID_01.fcs_110     0    0     0      0        0
    ## Experiment_AID_01.fcs_111     0    0     0      0        0
    ## Experiment_AID_01.fcs_112     0    0     0      0        0
    ## Experiment_AID_01.fcs_113     1    1     0      0        0
    ## Experiment_AID_01.fcs_114     0    0     0      0        0
    ## Experiment_AID_01.fcs_115     1    0     0      1        0

### Filter for a population

We can filter our data set for a population of interest e.g. the CD45+ cells.

    #select cell IDs of all CD45+ cells
    keep <- condor$anno$cell_anno[condor$anno$cell_anno$`CD45+` == 1,] %>% rownames()

    #check the number of CD45+ cells
    length(keep)

    ## [1] 2113826

    #filter data for CD45+ cells
    condor_CD45 <- filter_fcd(condor, cell_ids = keep)

#### Simple visualization of the dataset with FlowJo gating

We can visualize the gated cell populations for example in a simple dot plot. In the plot below, we plot the fluorescence intensity of CD3 against CD19 and color the cells by the ‘CD3+’ population from the FlowJo workspace.

    # subset condor to 10000 cells for visualization
    condor_sub <- subset_fcd(condor_CD45, size= 10000)

    #prepare data frame for plotting
    tmp <- cbind(condor_sub$expr$orig, condor_sub$anno$cell_anno)

    ggplot(tmp, aes(x= `CD19`, y = `CD3`, color = as.factor(`CD3+`))) +
      geom_point() +
      theme_bw() +
      theme(aspect.ratio = 1) +
      scale_color_viridis_d()

We can now continue with the usual `cyCONDOR` workflow (see e.g. `vignette("Dimensionality_Reduction")`, `vignette("Clustering_and_cell_annotation")` and `vignette("Data_Visualization")`.

## Session Info

    info <- sessionInfo()

    info

    ## R version 4.4.2 (2024-10-31)
    ## Platform: x86_64-pc-linux-gnu
    ## Running under: Ubuntu 24.04.1 LTS
    ##
    ## Matrix products: default
    ## BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    ## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    ##
    ## locale:
    ##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    ##  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8
    ##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8
    ##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C
    ##  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    ## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
    ##
    ## time zone: Etc/UTC
    ## tzcode source: system (glibc)
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] dplyr_1.1.4          ggplot2_3.5.2        Biobase_2.66.0
    ## [4] BiocGenerics_0.52.0  CytoML_2.18.3        flowWorkspace_4.18.1
    ## [7] cyCONDOR_0.3.1
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] IRanges_2.40.1              Rmisc_1.5.1
    ##   [3] urlchecker_1.0.1            nnet_7.3-20
    ##   [5] CytoNorm_2.0.1              TH.data_1.1-3
    ##   [7] vctrs_0.6.5                 digest_0.6.37
    ##   [9] png_0.1-8                   shape_1.4.6.1
    ##  [11] proxy_0.4-27                slingshot_2.14.0
    ##  [13] ggrepel_0.9.6               corrplot_0.95
    ##  [15] parallelly_1.45.0           MASS_7.3-65
    ##  [17] pkgdown_2.1.3               reshape2_1.4.4
    ##  [19] httpuv_1.6.16               foreach_1.5.2
    ##  [21] withr_3.0.2                 ggrastr_1.0.2
    ##  [23] xfun_0.52                   ggpubr_0.6.1
    ##  [25] ellipsis_0.3.2              survival_3.8-3
    ##  [27] memoise_2.0.1               hexbin_1.28.5
    ##  [29] ggbeeswarm_0.7.2            RProtoBufLib_2.18.0
    ##  [31] princurve_2.1.6             profvis_0.4.0
    ##  [33] ggsci_3.2.0                 systemfonts_1.2.3
    ##  [35] ragg_1.4.0                  zoo_1.8-14
    ##  [37] GlobalOptions_0.1.2         DEoptimR_1.1-3-1
    ##  [39] Formula_1.2-5               promises_1.3.3
    ##  [41] scatterplot3d_0.3-44        httr_1.4.7
    ##  [43] rstatix_0.7.2               globals_0.18.0
    ##  [45] rstudioapi_0.17.1           UCSC.utils_1.2.0
    ##  [47] miniUI_0.1.2                generics_0.1.4
    ##  [49] ggcyto_1.34.0               base64enc_0.1-3
    ##  [51] curl_6.4.0                  S4Vectors_0.44.0
    ##  [53] zlibbioc_1.52.0             polyclip_1.10-7
    ##  [55] randomForest_4.7-1.2        GenomeInfoDbData_1.2.13
    ##  [57] SparseArray_1.6.2           RBGL_1.82.0
    ##  [59] ncdfFlow_2.52.1             RcppEigen_0.3.4.0.2
    ##  [61] xtable_1.8-4                stringr_1.5.1
    ##  [63] desc_1.4.3                  doParallel_1.0.17
    ##  [65] evaluate_1.0.4              S4Arrays_1.6.0
    ##  [67] hms_1.1.3                   glmnet_4.1-9
    ##  [69] GenomicRanges_1.58.0        irlba_2.3.5.1
    ##  [71] colorspace_2.1-1            harmony_1.2.3
    ##  [73] reticulate_1.42.0           readxl_1.4.5
    ##  [75] magrittr_2.0.3              lmtest_0.9-40
    ##  [77] readr_2.1.5                 Rgraphviz_2.50.0
    ##  [79] later_1.4.2                 lattice_0.22-7
    ##  [81] future.apply_1.20.0         robustbase_0.99-4-1
    ##  [83] XML_3.99-0.18               cowplot_1.2.0
    ##  [85] matrixStats_1.5.0           xts_0.14.1
    ##  [87] class_7.3-23                Hmisc_5.2-3
    ##  [89] pillar_1.11.0               nlme_3.1-168
    ##  [91] iterators_1.0.14            compiler_4.4.2
    ##  [93] RSpectra_0.16-2             stringi_1.8.7
    ##  [95] gower_1.0.2                 minqa_1.2.8
    ##  [97] SummarizedExperiment_1.36.0 lubridate_1.9.4
    ##  [99] devtools_2.4.5              plyr_1.8.9
    ## [101] crayon_1.5.3                abind_1.4-8
    ## [103] locfit_1.5-9.12             sp_2.2-0
    ## [105] sandwich_3.1-1              pcaMethods_1.98.0
    ## [107] codetools_0.2-20            multcomp_1.4-28
    ## [109] textshaping_1.0.1           recipes_1.3.1
    ## [111] openssl_2.3.3               Rphenograph_0.99.1
    ## [113] TTR_0.24.4                  bslib_0.9.0
    ## [115] e1071_1.7-16                destiny_3.20.0
    ## [117] GetoptLong_1.0.5            ggplot.multistats_1.0.1
    ## [119] mime_0.13                   splines_4.4.2
    ## [121] circlize_0.4.16             Rcpp_1.1.0
    ## [123] sparseMatrixStats_1.18.0    cellranger_1.1.0
    ## [125] knitr_1.50                  clue_0.3-66
    ## [127] lme4_1.1-37                 fs_1.6.6
    ## [129] listenv_0.9.1               checkmate_2.3.2
    ## [131] DelayedMatrixStats_1.28.1   Rdpack_2.6.4
    ## [133] pkgbuild_1.4.8              ggsignif_0.6.4
    ## [135] tibble_3.3.0                Matrix_1.7-3
    ## [137] rpart.plot_3.1.2            statmod_1.5.0
    ## [139] tzdb_0.5.0                  tweenr_2.0.3
    ## [141] pkgconfig_2.0.3             pheatmap_1.0.13
    ## [143] tools_4.4.2                 cachem_1.1.0
    ## [145] rbibutils_2.3               viridisLite_0.4.2
    ## [147] smoother_1.3                fastmap_1.2.0
    ## [149] rmarkdown_2.29              scales_1.4.0
    ## [151] grid_4.4.2                  usethis_3.1.0
    ## [153] broom_1.0.8                 sass_0.4.10
    ## [155] graph_1.84.1                carData_3.0-5
    ## [157] RANN_2.6.2                  rpart_4.1.24
    ## [159] farver_2.1.2                reformulas_0.4.1
    ## [161] yaml_2.3.10                 MatrixGenerics_1.18.1
    ## [163] foreign_0.8-90              ggthemes_5.1.0
    ## [165] cli_3.6.5                   purrr_1.1.0
    ## [167] stats4_4.4.2                lifecycle_1.0.4
    ## [169] uwot_0.2.3                  askpass_1.2.1
    ## [171] caret_7.0-1                 mvtnorm_1.3-3
    ## [173] lava_1.8.1                  sessioninfo_1.2.3
    ## [175] backports_1.5.0             cytolib_2.18.2
    ## [177] timechange_0.3.0            gtable_0.3.6
    ## [179] rjson_0.2.23                umap_0.2.10.0
    ## [181] ggridges_0.5.6              parallel_4.4.2
    ## [183] pROC_1.18.5                 limma_3.62.2
    ## [185] jsonlite_2.0.0              edgeR_4.4.2
    ## [187] RcppHNSW_0.6.0              Rtsne_0.17
    ## [189] FlowSOM_2.14.0              ranger_0.17.0
    ## [191] flowCore_2.18.0             jquerylib_0.1.4
    ## [193] timeDate_4041.110           shiny_1.11.1
    ## [195] ConsensusClusterPlus_1.70.0 htmltools_0.5.8.1
    ## [197] diffcyt_1.26.1              glue_1.8.0
    ## [199] XVector_0.46.0              VIM_6.2.2
    ## [201] gridExtra_2.3               boot_1.3-31
    ## [203] TrajectoryUtils_1.14.0      igraph_2.1.4
    ## [205] R6_2.6.1                    tidyr_1.3.1
    ## [207] SingleCellExperiment_1.28.1 labeling_0.4.3
    ## [209] vcd_1.4-13                  cluster_2.1.8.1
    ## [211] pkgload_1.4.0               GenomeInfoDb_1.42.3
    ## [213] ipred_0.9-15                nloptr_2.2.1
    ## [215] DelayedArray_0.32.0         tidyselect_1.2.1
    ## [217] vipor_0.4.7                 htmlTable_2.4.3
    ## [219] ggforce_0.5.0               CytoDx_1.26.0
    ## [221] car_3.1-3                   future_1.58.0
    ## [223] ModelMetrics_1.2.2.2        laeken_0.5.3
    ## [225] data.table_1.17.8           htmlwidgets_1.6.4
    ## [227] ComplexHeatmap_2.22.0       RColorBrewer_1.1-3
    ## [229] rlang_1.1.6                 remotes_2.5.0
    ## [231] colorRamps_2.3.4            ggnewscale_0.5.2
    ## [233] hardhat_1.4.1               beeswarm_0.4.0
    ## [235] prodlim_2025.04.28