v0.9.0

[earmingol]

Release Notes - cell2cell v0.9.0

New features

• New 'trimean' aggregation method for single cells: aggregate_single_cells in
  cell2cell.preprocessing.rnaseq accepts method='trimean' to aggregate the gene expression of the
  single cells composing a cell type using Tukey's trimean (0.5 * Q2 + 0.25 * (Q1 + Q3)), computed
  with a new cell2cell.preprocessing.rnaseq._trimean helper. It is a weighted average of the median
  and the first and third quartiles, so it is more robust to outliers than the average while still
  accounting for the spread of the distribution, and it ignores NaNs. It is also available through the
  aggregation_method parameter of SingleCellInteractions in cell2cell.analysis.

• New dependency natsort: Element names are now sorted using natural sorting (natsorted)
  instead of lexicographic sorting (sorted) across the package. Names containing numbers are ordered
  as expected (e.g. Factor 1, Factor 2, ..., Factor 10 instead of Factor 1, Factor 10, Factor 2, ...,
  and C-1, C-2, C-10 instead of C-1, C-10, C-2).

Feature updates

• Natural sorting of element names: sorted() was replaced with natsorted() in the functions
  that define the order of element names, including build_context_ccc_tensor and dataframes_to_tensor
  in cell2cell.tensor (tensor gene, cell, LR-pair and context orders), add_sliding_window_info_to_adata
  in cell2cell.spatial (window column names), run_label_permutation in cell2cell.stats,
  initialize_interaction_space in cell2cell.analysis, get_filtered_ppi_network and
  get_genes_from_go_hierarchy in cell2cell.preprocessing, get_files_from_directory in cell2cell.io,
  aggregate_single_cells in cell2cell.preprocessing (order of the aggregated cell types),
  and generate_legend, pcoa_3dplot, context_boxplot and circos_plot in cell2cell.plotting.

• Reproducible order of elements: Multiple functions obtained the order of their elements from a
  Python set, which is not reproducible across runs. These now return a deterministic order:

  • generate_pairs in cell2cell.core.interaction_space keeps the order given by the list of cells
    when removing duplicated pairs, which also defines the column order of the communication matrix.
  • get_element_abundances in cell2cell.preprocessing.find_elements keeps the order in which
    elements are first found, making the how='outer' options of the tensor builders reproducible.
  • dataframes_to_tensor in cell2cell.tensor keeps the order in which elements appear in the
    input dataframes when sort_elements=False.
  • random_switching_ppi_labels in cell2cell.stats.permutation sorts the genes before permuting
    them, so results are now reproducible for a given random_state when a list of genes is passed.
  • circos_plot and context_boxplot in cell2cell.plotting produce a reproducible order of
    cells, nodes and groups.

• Note on the order of results: Because of the changes above, the order of the elements in some
  outputs may differ from previous versions (tensor dimensions, columns of the communication matrix,
  order of groups and legends in plots, and permutations obtained with a fixed random_state). The
  values themselves are unchanged. Lexicographic sorting was intentionally kept in
  remove_ppi_bidirectionality in cell2cell.preprocessing.ppi because it determines which direction
  of a bidirectional interaction is kept, so its results remain identical to previous versions.

Fixed Bugs

• Wrong cell-pair labels in flatten_factor_ccc_networks: This function in
  cell2cell.analysis.tensor_downstream built the names of the sender-receiver pairs from the
  sorted names of the cells, but flattened the loadings of the factor-specific networks in the order
  the cells have in the tensor. When the elements of the sender and receiver dimensions of the tensor
  were not alphabetically sorted, every loading was assigned to the wrong sender-receiver pair. The
  names of the cell pairs are now built directly from the adjacency matrices, keeping the order of the
  tensor dimensions, and the matrices are reindexed before flattening so that values and labels always
  match. get_lr_by_cell_pairs used this function internally, so its results were affected too.
  Results and figures generated from tensors whose sender/receiver elements were not alphabetically
  sorted should be regenerated. Results obtained from tensors with alphabetically sorted elements
  were not affected and are identical to previous versions.

• Factor order in tensor downstream analyses: get_factor_specific_ccc_networks and
  compute_gini_coefficients in cell2cell.analysis.tensor_downstream sorted the factor names
  lexicographically, so decompositions with 10 or more factors were returned in the order
  Factor 1, Factor 10, Factor 11, Factor 2, .... They are now naturally sorted.

• Factor names in get_lr_by_cell_pairs: This function assumed that every factor was named
  '<word> <integer>' and raised an error with any other naming. It now uses natural sorting instead
  of parsing the factor names.

• aggregate_single_cells modified the dataframe passed by the user: This function in
  cell2cell.preprocessing.rnaseq replaced the index of the input dataframe with the cell types and
  added a 'celltype' column to it, modifying it in place. As a consequence, calling the function
  twice on the same dataframe raised a KeyError. It now groups the single cells by an external list
  of cell types, leaving the input untouched (without copying the expression matrix). The aggregated
  values are unchanged; only the column order may differ, as the cell types are now naturally sorted.

• add_sliding_window_info_to_adata with pandas >= 2.0: This function in cell2cell.spatial
  passed a set of barcodes to DataFrame.loc, which newer versions of pandas do not accept. The
  barcodes are now passed as a list.

• Docstring of flatten_factor_ccc_networks: It stated that rows were factors and columns were
  cell-cell pairs, while the returned dataframe contains the cell-cell pairs as rows and the factors
  as columns.