LogicComm 0.13.0

LogicComm 0.13.0

Breaking change: removed the transitional neighborhood / spatial-range output

The inert neighborhood/local/distal/range fields that v0.12 kept as
back-compatible stubs are now removed, so the output schema matches what the
cell-type co-expression method actually computes. This resolves a direct
contradiction in which the method documentation disavowed spatial
juxtacrine/paracrine claims while the output still carried n_juxtacrine,
n_paracrine, n_distal, communication_range, and "local vs global graph
support" labels referencing a per-cell graph that no longer exists.

• summarize_celltype_communication() lr_table no longer contains
  lcs_neighborhood, lcs_primary_mode, communication_range,
  n_active_neighborhood, active_edge_weight_sum, local_active,
  distal_candidate, global_candidate_active, or candidate_active. The
  honest cell-type columns remain (lcs, lcs_global, lcs_unweighted,
  n_edges/edge_weight_sum = the sender x receiver opportunity universe,
  n_active_edges = co-expression support, the per-side active counts/fractions,
  and active).
• pair_summary and pathway_summary drop communication_support_label,
  local_support_fraction_active, n_local_active, n_distal_candidate,
  n_global_candidate_active, n_juxtacrine, n_paracrine, n_distal,
  dominant_communication_range, sum_active_edge_weight, and
  active_edge_weight_sum.
• summarize_spatial_communication() is removed. After the v0.12 neighborhood
  removal it was a placeholder that built coordinates, warned, and returned
  ordinary cell-type co-expression -- it never used a spatial graph and produced
  no spatially resolved result. The spatial utilities build_spatial_graph()
  (kNN/radius graph construction) and plot_spatial_logic() (per-spot REO
  visualization) remain; use summarize_celltype_communication() /
  discover_celltype_communication() for communication scores. A genuine spatial
  edge scorer would require physical-distance edges and a spatial permutation
  null, and is intentionally out of scope rather than faked by a wrapper.
• plot_communication_range_summary() is removed; it visualized a signaling
  "range" the method no longer resolves. plot_celltype_network() drops its
  color_edges_by = "range" mode and distal/global edge styling and now colours
  edges by top pathway. plot_lr_bubble_advanced() and
  plot_lr_activity_balance() colour by LCS instead of range.
• summarize_communication_findings() drops distal_candidate_pairs and the
  graph-support guide rows; write_communication_report() drops the
  distal-candidate section and the KNN/neighborhood cautions.
• logic_grade_evidence() now grades on the evidence the cell-type model
  produces -- an active co-expression call, optionally corroborated by attached
  orthogonal validation -- rather than the removed local/distal/global graph
  distinction (grade A = active + validation, B = active, otherwise
  insufficient).
• diagnose_celltype_communication() no longer reports n_distal_candidates.

Documentation

• Aligned every prose description of the method with the actual cell-type
  co-expression model. The manuscript (inst/manuscript) no longer presents the
  removed per-cell KNN/SNN neighborhood scoring as a current feature (abstract,
  introduction, methods, and figure captions were corrected, the stale test
  count updated, and the PBMC empirical sections flagged for regeneration against
  the v0.13 scorer); the README dropped the "KNN/SNN graph: optional but
  recommended" claim; and the LogicComm-intro overview no longer describes a
  "neighboring receiver cell".
• DESCRIPTION no longer advertises "weighted graph scoring" or spatial
  communication "modules"; it describes cell-type REO co-expression scoring, the
  discovery workflow, and the spatial graph/visualization utilities.

Fixes

• Fixed logic_summarize_celltypes() emitting a spurious "knn_mat, graph_name,
  remove_self_edges are deprecated and ignored" warning on every call. The
  wrapper still declared and unconditionally forwarded those (now removed)
  neighborhood parameters, and the deprecation shim warns on argument
  presence, so even a default call with no neighborhood intent warned. The dead
  parameters (knn_mat, graph_name, mode, remove_self_edges) were dropped
  from the wrapper; scoring options now flow through ..., and an explicitly
  supplied legacy argument still warns (correctly) at
  summarize_celltype_communication().
• Fixed score_receiver_response() (and therefore
  add_receiver_response_score()), which errored with "subscript out of bounds"
  in the standard workflow. It indexed ct_comm$cell_labels by
  colnames(reo_mat), so any reo_mat cell absent from the labels (the normal
  case once summarize_celltype_communication() has filtered cells with
  missing/empty labels and the original reo_mat is passed back) produced NA
  labels and NA cell names that leaked into the receiver-cell selection. Labels
  and reo_mat are now aligned to their shared cells first. Regression test added.
• Fixed calc_rank_shift() to rank each gene within the cell's full
  transcriptome, as its documentation describes (and as calc_REO_matrix()
  anchors), instead of within the small L-R panel. The matrix was being subset to
  the ~120 L-R genes before ranking, so a transcriptome-dominant ligand was
  scored as mid-ranked among the panel and the transcriptome-wide rank shift the
  method is designed to detect was lost (on a 200-gene example the normalized rank
  of a dominant gene differed ~37-fold between the two definitions). The fix ranks
  over all expressed genes per cell while storing only the target genes' ranks, so
  memory stays bounded. Also corrected mean_expr_*/log2fc_expr to average each
  gene over the samples that contain it rather than the full sample count.
  Regression test added.
• Fixed cell-type role assignment so that Mediator and Influencer can actually
  be dominant roles. dominant_role (and secondary_role / role separation)
  are now derived from the four role scores rescaled to a common [0, 1] scale
  across cell types, matching plot_celltype_role_radar(). Previously the raw
  scores were compared directly even though they live on incomparable scales
  (Sender/Receiver are summed LCS, mediator betweenness is normalized to [0, 1],
  and the PageRank influencer score sums to 1 over cell types, ~1/n each), so
  almost every cell type collapsed to Sender or Receiver and a textbook bridge
  cell type was mislabelled. The raw sender_role_score, receiver_role_score,
  mediator_role_score, and influencer_role_score columns are unchanged; only
  the derived role labels improve. Regression test added.
• run_multisample() no longer takes the dead neighborhood parameters
  (knn_list, graph_name, remove_self_edges, graph_symmetrize,
  edge_weight_mode). They had no effect since the v0.12 neighborhood removal --
  IdentifyLogicConsensus() scores from global REO co-expression -- yet were
  silently accepted and match.arg-validated. They are now accepted via ...
  and ignored with a deprecation warning, consistent with
  IdentifyLogicConsensus() and summarize_celltype_communication().
• Removed a duplicate internal .resolve_complex_rank(). Two definitions
  existed; because R sources package files in the C locale, the canonical
  modulators.R version (NA for missing subunits, conservative "min"
  aggregation) always shadowed the celltype_communication.R copy, which was
  therefore dead code whose survival depended on file collation order. Cell-type
  rank weighting only reads ranks where the complex logic is active (all subunits
  present, hence finite), so results are unchanged.
• R CMD check is clean: regenerated stale man/ pages (codoc mismatches for
  summarize_celltype_communication(), permute_celltype_communication(),
  IdentifyLogicConsensus(), and logic_score_lr()), documented
  discover_celltype_communication(), added the missing @param entries on the
  volcano and discovery plots, removed orphan internal Rd files, and registered
  the significance ggplot aesthetic as a global variable.