v0.18.2

Fixes

• Fixed an edge case bug in ProximityScoresToAssay where components would be dropped if they only have 0 for proximity scores.

Updates

• Added layout_method "cpmds" (layout_with_coarsened_pmds) option to ComputeLayout.

v0.18.1

Fixes

• Fixed a bug in the tbl_lazy method for ProximityScoresToAssay where the proximity scores were incorrectly mapped to protein pairs and components.

Changes

• Removed option return_sparse from ProximityScoresToAssay (tbl_lazy and data.frame methods). These methods now always return a sparse matrix (dgCMatrix).
• Removed option missing_obs from ProximityScoresToAssay. Missing observations are now set to 0.
• Added option lazy to ProximityScoresToAssay (PNAAssay and Seurat methods) to enable lazy evaluation of proximity scores.

v0.18.0

Added

• layout_with_coarsened_pmds layout method for faster and more accurate PNA cell graph layouts.
• ComputeProximityScores methods to compute global proximity scores for cell graphs. The method also enables computing proximity scores for k > 1 neighborhoods (lower spatial resolution), but this option is limited to log2 ratios (no Z scores).
• heuristic_illumination to approximate natural illumination of a 3D layout.
• Illumination masking option in render_rotating_layout to modulate node_val colors with a heuristic illumination mask.
• Shadow palette blending in render_rotating_layout via illumination_shadow_colors for palette-based shadow interpolation.
• normalize_illumination argument in render_rotating_layout to optionally disable rescaling of the illumination mask to [0, 1].
• "NaturalBlue" option as a gradient palette in PixelgenGradient to use as a natural illuminated color gradient.

Updated

• Changed the default proximity score in ProximityScoresToAssay from "join_count_z" to "log2_ratio"
• ProximityScoresToAssay now takes a separator argument to specify the character used to separate marker names. The default separator is changed from / to : to avoid misinterpretation of marker names containing /.
• approximate_node_saturation, approximate_edge_saturation and approximate_saturation_curve now uses the standard definition of saturation (s = 1 - molecules / reads).
• ReadPNA_Seurat will now throw an informative error when reading a file with only a single cell, which would otherwise throw a cryptic error when trying to create the Seurat object.

Fixes

• Fixed a bug in SummarizeProximityScores where the include_missing_obs argument was not properly handled when include_missing_obs = FALSE.
• Added an explicit error message in SummarizeProximityScores for when there are duplicate rows in the input Proximity Score table.

v0.17.1

Updated

• Added scaling to isotype_pls and changed default layer to "data" to avoid issues where some markers are missing from the "scale.data" layer.
• render_rotating_layout now accepts max_degree down to 0 degrees instead of 90 degrees as a minimum.

Fixes

• Fixed a bug where running AnnotateCells(..., method = "nmf") could unintentionally propagate normalization changes from an internal temporary Seurat object to the returned object.
• Fixed a bug in render_rotating_layout to explicitly use graphics::layout to avoid an error being triggered when having plotly loaded.

v0.17.0

Added

• Added CalculateDispersion method for calculating dispersion of counts across features and cells. Currently "tau" and "gini" dispersion metrics are supported. This method is useful for identifying outliers in the count data, for example to identify cells with an unusual count distribution across markers.
• Added a new gradient color palette "BluesGrayCherry" to PixelgenGradient.

Fixes

• Fixed bug in FSMap<- when handling Seurat objects multiple PNA/MPX assays. Previously, FSMap would only update the active assay. Now, the Seurat object is scanned for all PNA/MPX assays and updates them with value.
• Fixed a bug in SequenceSaturationCurve that would throw an error when there are int64 columns in the edgelist.

v0.16.0

Updated

• Added option to ignore low transition probability edges in expand_adjacency_matrix when use_weights = TRUE.
• Switched to using svds from RSpectra to compute MDS in layout_with_weighted_pmds for a performance boost
• Switched to using pattern matrix representation of the adjacency matrix in expand_adjacency_matrix for a performance boost

Added

• Added reference PBMC dataset and load function read_pbmc_reference that can be used for annotation.
• Added isotype_pls to calculate isotype background score.
• Added export_plot utility function to export ggplot objects to file.
• Added create_discrete_palette to create palettes to color different samples or conditions.
• Added Pixelgen_cell_palette, a named vector of colors assigned to cell types.

Fixes

• Fixed bug in SequenceSaturationCurve where the node saturation would be calculated as 1 - graph_proteins / (2 * graph_reads) instead of 1 - graph_proteins / graph_reads.
• DuckDB temporary directory can now be set with PIXELATOR_DUCKDB_TEMP_DIR
• Fixed bug in render_rotating_layout when center_zero = TRUE and the most extreme values were negative. Now the color scale should be centered properly.

v0.15.0

Added

• new sequencing saturation and graph stability functions.

  • approximate_edge_saturation computes edge saturation for components in a PXL file
  • approximate_node_saturation computes node saturation for components in a PXL file
  • approximate_saturation_curve computes node/edge saturation for downsampled components in a PXL file
  • downsample_to_parquet downsamples the edgelist in a PXL file and exports these edgelists to parquet files
  • lcc_sizes computes the largest connected components for cell components in downsampled edgeslists (parquet files)
  • lcc_curve computes LCC for downsampled components in a PXL file using the duckpgq DuckDB extension

• sequencing_saturation and SequenceSaturationCurve to compute sequencing saturation statistics from an edgelist.

• Updated

• approximate_edge_saturation and approximate_node_saturation now accepts a components argument for filtering.

• Added an argument union to control whether tables of lazy tables should be joined or output as a list in .lazy_load_table and Edgelists.

• AnnotateCells now returns columns named exactly as reference_groups

Fixed

• Fixed a bug in .lazy_load_table that prevented lazy loading of tables.

v0.14.0

Added

• Supervised patch detection implemented in the patch_detection function. Added identify_markers_for_patch_analysis to identify markers for patch analysis.
• render_rotating_layout function to create videos of rotating cells from a tibble containing layout coordinates. The function supports multiple video formats but uses GIF as default.
• subset method for CellGraph class
• Option to add marker count proportions to the proximity score table in ProximityScores
• pack_2bits and unpack_2bits to pack and unpack DNA sequences into 64-bit integers using 2 bits per base.
• Experimental PredictDoublets function for detecting doublets in a Seurat object or count matrix.
• SimulateDoublets to simulate doublets.
• FindAnnoyNeighbors Computes nearest neighbors using the Annoy algorithm.
• DensityScatterPlot now has an argument equal_axes to control whether the x and y axes should have a common range.
• return_id argument to SimulateDoublets to output the IDs of cells used to simulate each doublet.

Fixes

• Fixed bug in ColocalizationHeatmap where marker1_col and marker2_col only worked for "marker_1" and "marker_2".
• Fixed bug in DensityScatterPlot where the % cells label would be calculated across all facets instead of per each facet.

v0.13.0

pixelatorR 0.13.0

This release introduces a suite of powerful new features designed to streamline the loading, processing, analysis, and visualization of Proximity Network Assay (PNA) data. Central to this update is the introduction of the PixelDB R6 class, providing a robust interface for interacting with the newly supported PXL file format. We've included specialized functions for reading data directly from PXL files into R. Furthermore, two new assay classes have been developed specifically to represent PNA data effectively within the Seurat analysis framework. These core components are complemented by a wide range of new methods and enhancements across the analysis pipeline. See below for a detailed list of additions and modifications.

Added

• PixelDB R6 class to access data from a PXL file (<pxl_file>) containing a duckdb database.
  • PixelDB$new create a new PixelDB object from a PXL file containing PNA data.
  • PixelDB$info get information about the tables stored in the PXL file.
  • PixelDB$query send an SQL query to the database.
  • PixelDB$check_connection check if the connection to the PXL file is still valid.
  • PixelDB$reconnect reconnect to the database if the connection is closed.
  • PixelDB$names get the names of the tables stored in the database.
  • PixelDB$fetch_table fetch an entire table as a data.frame.
  • PixelDB$fetch_table_subset fetch a subset of a table as a data.frame
  • PixelDB$counts fetch the antibody count matrix.
  • PixelDB$proximity fetch the proximity scores table.
  • PixelDB$cell_meta fetch the component/cell meta data.
  • PixelDB$protein_meta fetch the protein meta data.
  • PixelDB$run_meta fetch the Pixelator run meta data.
  • PixelDB$components_edgelist fetch the edgelist(s) for selected components/cells.
  • PixelDB$components_layout fetch the layout(s) for selected components/cells.
  • PixelDB$components_marker_counts fetch the node counts for selected component/cell graphs.
  • PixelDB$export_parquet export a table in the database to a parquet file.
  • PixelDB$close close the connection.
• ReadPNA_counts function to load the count matrix from a PXL file containing PNA data.
• ReadPNA_proximity function to load the proximity scores table from a PXL file containing PNA data. Also supports lazy loading.
• ReadPNA_edgelist function to load the edgelist from a PXL file containing PNA data. Also supports lazy loading.
• ReadPNA_layouts function to load component layouts from a PXL file containing PNA data with pre-computed layouts.
• ReadPNA_Seurat function to construct a Seurat object from a PXL file containing PNA data.
• ReadPNA_metadata function to load sample meta data from a PXL file containing PNA data.
• PNAAssay class to store PNA data in a Seurat object (v3).
• CreatePNAAssay to create a PNAAssay object.
• PNAAssay5 class to store PNA data in a Seurat object (v5).
• CreatePNAAssay5 to create a PNAAssay5 object.
• Edgelists methods for PNAAssay, PNAAssay5 and Seurat to load edgelists. Supports lazy loading for manipulation with dbplyr.
• ProximityScores methods for PNAAssay, PNAAssay5 and Seurat to fetch proximity scores. Supports lazy loading for manipulation with dbplyr.
• ProximityScores<- methods for PNAAssay, PNAAssay5 and Seurat to set proximity scores.
• ProximityScoresToAssay methods for data.frame, tbl_lazy, PNAAssay, PNAAssay5 and Seurat to convert the long formatted proximity score table into a wide format.
• LoadCellGraphs methods for for PNAAssay and PNAAssay5.
• ComputeLayout methods for for PNAAssay and PNAAssay5.
• RemoveCellGraphs methods for for PNAAssay and PNAAssay5.
• CellGraphs methods for for PNAAssay and PNAAssay5.
• RestorePaths methods for for PNAAssay and PNAAssay5.
• FSMap/FSMap<- methods for PNAAssay and PNAAssay5.
• show method for PNAAssay and PNAAssay5.
• subset method for PNAAssay and PNAAssay5.
• merge method for PNAAssay and PNAAssay5.
• RenameCells methods for PNAAssay and PNAAssay5.
• JoinLayers method for PNAAssay5.
• as.PNAAssay method to convert an Assay object to a PNAAssay object.
• as.PNAAssay5 method to convert an Assay5 object to a PNAAssay5 object.
• DifferentialProximityAnalysis function to perform differential testing on PNA proximity scores. The function has a similar API as RunDAA, RunDPA and RunDCA but uses a much faster implementation of the Wilcoxon rank sum test (Mann-Whitney U test) with the data.table R package.
• A minimal PXL file woth PNA data.
• minimal_mpx_pxl_file function to get the path to the minimal MPX PXL file.
• minimal_mpx_pna_file function to get the path to the minimal PNA PXL file.
• Utility function for asserting valid colors; assert_valid_color.
• Utility function for asserting valid PNAAssay/PNAAssay5; assert_pna_assay.
• Utility function for asserting valid PNAAssay/PNAAssay5/CellGraphAssay/CellGraphAssay5; assert_pna_assay.

Updates

• MoleculeRankPlot now supports Seurat objects with PNA data with n_umi representing the total number of detected antibodies.
• TauPlot now supports Seurat objects with PNA data using n_umi on the y-axis.
• Plot2DGraph now supports Seurat objects with PNA data.
• Plot2DGraphM now supports Seurat objects with PNA data.
• Plot3DGraph now supports Seurat objects with PNA data.
• DensityScatterPlot can now draw rectangle or quadrant gates by selecting the appropriate gate_type argument. Additionally, gate annotation aesthetics can now be customized using annotation_params.

Changes

• ComputeLayout now only supports the "pmds" and "wpmds" graph drawing methods. The "kk", "fr" and "drl" methods have been removed but can be run if needed using the custom_layout_function parameter. The default layout method is now "wpmds" with dim = 3.
• NormalizeMPX is superseded by Normalize. The NormalizeMPX function will be removed in a future release.

Removed

• LoadCellGraphs.data.frame method

Fixes

• Fixed bug in DensityScatterPlot where the gate_type default would lead to an error.
• Fixed bug in DensityScatterPlot where the x- and y-axis titles were hardcoded as "Marker1" and "Marker2"
• Fixed bug in subset.MPXAssay and subset.PNAAssay where the fs_map table was not filtered correctly when all components from a sample are removed.

v0.12.0

Added

• RunDAA : Differential abundance analysis function with a similar interface to RunDPA and RunDCA. RunDAA uses the FindMarkers function from Seurat to perform differential abundance analysis, but enables splitting of tests into multiple groups. By default, it reports the difference in means instead of avg_log2FC.

Updates

• Updated type assertions and improved error messaging (inspired by the tidyverse style guide).
• The ComputeLayout.Seurat method now supports parallelized computation of layouts.
• Added option to fetch marker counts in PolarizationScores and ColocalizationScores methods. This is for example useful when filtering spatial metrics tables for markers with low counts.
• Silenced warnings in RunDPA/RunDCA when running tests in parallel to avoid halting the R session.
• Improved clean up of temporary files created by ReadMPX_counts and ReadMPX_item.
• RunDPA and RunDCA now accepts any numeric vector from the spatial metric table as input for differential testing. The metric is specified by polarity_metric (RunDPA) or coloc_metric (RunDCA).
• Updated subset and merge methods for MPXAssay to have less stringent validation of the spatial metric tables (polarity and colocalization scores).
• Updated ReadMPX_Seurat to have less stringent validation of the spatial metric tables (polarity and colocalization scores).
• ColocalizationHeatmap now allows legend titles and the legend range to be manually set

Fixes

• pixelatorR read functions now uses utils::unzip instead of zip::unzip to support PXL files larger than 2GB
• LoadCellGraphs now throws an error if duplicated cell ids (cells) are provided
• PXL files missing spatial scores can now be loaded with ReadMPX_Seurat without throwing an error. This is useful when the pixelator pipeline was run without computing spatial scores.