Create Nanostring CosMx Giotto Object

Source: R/convenience_cosmx.R

Given the path to a CosMx experiment directory, creates a Giotto object.

createGiottoCosMxObject(
  cosmx_dir,
  version = "default",
  FOVs = NULL,
  feat_type = c("rna", "negprobes"),
  split_keyword = list("NegPrb"),
  load_images = list(composite = "composite", overlay = "overlay"),
  load_expression = FALSE,
  load_cellmeta = FALSE,
  fov_shifts_path = NULL,
  transcript_path = NULL,
  cell_labels_dir = NULL,
  expression_path = NULL,
  metadata_path = NULL,
  cores = determine_cores(),
  verbose = NULL,
  instructions = NULL,
  remove_unvalid_polygons = deprecated(),
  data_to_use = deprecated(),
  remove_background_polygon = deprecated(),
  background_algo = deprecated(),
  ...
)

Arguments

cosmx_dir

full path to the exported cosmx directory

version

character. Version of CosMx output. Current selections are either "default", "v6", and "legacy" (for the NSCLC dataset).

FOVs

field of views to load (only affects subcellular data and images)

feat_type

character. feature type. Provide more than one value if using the split_keyword param. For each set of keywords to split by, an additional feat_type should be provided in the same order. Affects how the transcripts information is loaded. Helpful for separating out the QC probes. See details.

split_keyword

list of character vectors of keywords to split the transcripts based on their feat_ID. Keywords will be grepl() matched against the feature IDs information. See details.

load_images

named list of filepaths to directories. Loads the composite and overlay images by default.

load_expression

logical. (Default = FALSE) whether to load provided expression matrix

load_cellmeta

logical. (Default = TRUE) whether to load provided cell metadata

fov_shifts_path

Optional. Filepath to fov_positions_file

transcript_path

Optional. Filepath to desired transcripts file to load.

cell_labels_dir

Optional. Path to directory containing CellLabels images to load as polygons.

expression_path

Optional. Filepath to cell feature matrix to load.

metadata_path

Optional. Filepath to metadata file to load.

cores

nthreads to use when loading in cell metadata and transcripts

verbose

be verbose when building Giotto object

instructions

list of instructions or output result from createGiottoInstructions

remove_unvalid_polygons

deprecated. Now always done

data_to_use

deprecated. Not used

remove_background_polygon

deprecated. Now always done

background_algo

deprecated. Not used

...

Arguments passed on to importCosMx

slide

numeric. Slide number. Defaults to 1

micron

logical. Whether to scale spatial information as micron instead of the default pixels

px2um

numeric. Scalefactor from pixels to micron. Defaults to 0.12028 based on `CosMx-ReadMe.html` info

Value

a giotto object

Details

[Expected Directory] This function generates a giotto object when given a link to a cosmx output directory. It expects the following items within the directory where the bolded portions are what this function matches against:

  • CellComposite (folder of images)

  • CellLabels (folder of images)

  • CellOverlay (folder of images)

  • CompartmentLabels (folder of images)

  • experimentname_exprMat_file.csv (file)

  • experimentname_fov_positions_file.csv (file)

  • experimentname_metadata_file.csv (file)

  • experimentname_tx_file.csv (file)

[feat_type and split_keyword] Additional QC probe information is in the subcellular feature detections information and must be separated from the gene expression information during processing. The QC probes have prefixes that allow them to be selected from the rest of the feature IDs. Giotto uses feat_type and split_keyword params to select these QC probes out as separate feature types. See examples in [GiottoClass::createGiottoPoints] for how this works.

The Gene expression subset labeled as rna is accepted as the subset of feat_IDs that do not get matched to any of the split_keywords.

[Images] Images in the expected CellComposite and CellOverlay folders will be loaded as giotto largeImage objects by default. showGiottoImageNames can be used to see the available images.