docs(panel): sync parameter descriptions (#7)

* Update PCA count type options

* Require PCA count type selection

* Update PCA point size default

* Update PCA label controls

* Update vendored MOSuite plotting defaults

* Revert "Update vendored MOSuite plotting defaults"

This reverts commit 35f0257.

* Sync MOSuite subtree to FigOutSync

* chore(syncweaver): update MOSuite source to main

_commit message is ai-generated_

* fix(pca): expose 2D PCA transform controls

* docs(pca): clarify log transform guidance

* docs(panel): sync parameter descriptions

_commit message is ai-generated_

* docs(changelog): add PR entry

* test: add syncweaver lock coverage

* test: remove syncweaver lock tests

* Update CHANGELOG.md

* test: add script to test w/ podman

* chore: bump MOSuite to v0.4.1

* test: remove redundant param tests

---------

Co-authored-by: Kelly Sovacool <kelly.sovacool@nih.gov>
Co-authored-by: Kelly Sovacool, PhD <kelly-sovacool@users.noreply.github.com>

Author: phoman14

.codeocean/app-panel.json

@@ -36,23 +36,25 @@
 			"category": "EzTg1ivlFDHEy9PI",
 			"name": "Count type",
 			"param_name": "count_type",
-			"description": "Type of counts to use (e.g., filt, norm)",
+			"description": "The type of counts to use when plotting a multiOmicDataSet.",
 			"type": "list",
 			"value_type": "string",
-			"default_value": "filt",
+			"default_value": null,
+			"required": true,
 			"extra_data": [
 				"raw",
 				"clean",
 				"filt",
-				"norm"
+				"norm",
+				"batch"
 			]
 		},
 		{
 			"id": "group_colname_id",
 			"category": "EzTg1ivlFDHEy9PI",
 			"name": "Group column name",
 			"param_name": "group_colname",
-			"description": "Column name for sample groups",
+			"description": "The column from the sample metadata containing the sample group information. This is usually a column showing to which experimental treatments each sample belongs, such as WildType, Knockout, Tumor, Normal, Before, or After.",
 			"type": "text",
 			"value_type": "string",
 			"default_value": "Group"
@@ -62,7 +64,7 @@
 			"category": "EzTg1ivlFDHEy9PI",
 			"name": "Label column name",
 			"param_name": "label_colname",
-			"description": "Column name for sample labels",
+			"description": "The column from the sample metadata containing the sample labels as you wish them to appear on the PCA plot. This can be the same Sample Names Column. You may select a different column with shorter labels for display on the figure. The selected column should contain unique names for each sample.",
 			"type": "text",
 			"value_type": "string",
 			"default_value": "Label"
@@ -72,7 +74,7 @@
 			"category": "7Rr6IxOMDucKMImp",
 			"name": "Sub count type",
 			"param_name": "sub_count_type",
-			"description": "Sub count type if count_type is a list",
+			"description": "Used when count_type refers to a list of count matrices.",
 			"type": "text",
 			"value_type": "string"
 		},
@@ -81,7 +83,7 @@
 			"category": "EzTg1ivlFDHEy9PI",
 			"name": "Sample ID column name",
 			"param_name": "sample_id_colname",
-			"description": "Column name for sample IDs",
+			"description": "The column from the sample metadata containing the sample names. The names in this column must exactly match the names used as sample column names in the input counts matrix.",
 			"type": "text",
 			"value_type": "string"
 		},
@@ -90,7 +92,7 @@
 			"category": "7Rr6IxOMDucKMImp",
 			"name": "Samples to rename",
 			"param_name": "samples_to_rename",
-			"description": "Samples to rename in format old:new,old2:new2",
+			"description": "Rename samples manually for display on the PCA plot. Use the format old_name:new_name.",
 			"type": "text",
 			"value_type": "string"
 		},
@@ -99,7 +101,7 @@
 			"category": "7Rr6IxOMDucKMImp",
 			"name": "Principal components",
 			"param_name": "principal_components",
-			"description": "Principal components to plot (comma-separated, e.g., 1,2)",
+			"description": "Vector with numbered principal components to plot. Use two principal components for a 2D PCA plot.",
 			"type": "text",
 			"value_type": "string",
 			"default_value": "1,2"
@@ -109,7 +111,7 @@
 			"category": "7Rr6IxOMDucKMImp",
 			"name": "Feature ID column name",
 			"param_name": "feature_id_colname",
-			"description": "Column name for feature IDs",
+			"description": "The column from the counts data containing the Feature IDs, usually Gene or Protein ID. This is usually the first column of the input counts matrix. Only columns of text type from the input counts matrix are available to select for this parameter.",
 			"type": "text",
 			"value_type": "string"
 		},
@@ -118,7 +120,7 @@
 			"category": "FvI4Z2eb9sjL47Jt",
 			"name": "Legend position",
 			"param_name": "legend_position",
-			"description": "Position of the legend",
+			"description": "Passed to legend.position in ggplot2::theme().",
 			"type": "list",
 			"value_type": "string",
 			"default_value": "top",
@@ -129,36 +131,31 @@
 				"right"
 			]
 		},
+		{
+			"id": "legend_font_size_id",
+			"category": "FvI4Z2eb9sjL47Jt",
+			"name": "Legend font size",
+			"param_name": "legend_font_size",
+			"description": "Font size for the PCA legend text. When no value is supplied, the size is scaled automatically based on the number and length of legend labels.",
+			"type": "text",
+			"value_type": "string"
+		},
 		{
 			"id": "point_size_id",
 			"category": "FvI4Z2eb9sjL47Jt",
 			"name": "Point size",
 			"param_name": "point_size",
-			"description": "Size of points in plot",
+			"description": "Size for ggplot2::geom_point().",
 			"type": "text",
 			"value_type": "string",
-			"default_value": "3"
-		},
-		{
-			"id": "add_label_id",
-			"category": "FvI4Z2eb9sjL47Jt",
-			"name": "Add labels",
-			"param_name": "add_label",
-			"description": "Whether to add labels to points",
-			"type": "list",
-			"value_type": "string",
-			"default_value": "TRUE",
-			"extra_data": [
-				"TRUE",
-				"FALSE"
-			]
+			"default_value": "5"
 		},
 		{
 			"id": "label_font_size_id",
 			"category": "FvI4Z2eb9sjL47Jt",
 			"name": "Label font size",
 			"param_name": "label_font_size",
-			"description": "Font size for labels",
+			"description": "Font size for text labels on the PCA plot.",
 			"type": "text",
 			"value_type": "string",
 			"default_value": "3"
@@ -168,7 +165,7 @@
 			"category": "FvI4Z2eb9sjL47Jt",
 			"name": "Label offset X",
 			"param_name": "label_offset_x_",
-			"description": "X-axis offset for labels",
+			"description": "Horizontal offset for text labels on the PCA plot.",
 			"type": "text",
 			"value_type": "string",
 			"default_value": "2"
@@ -178,17 +175,31 @@
 			"category": "FvI4Z2eb9sjL47Jt",
 			"name": "Label offset Y",
 			"param_name": "label_offset_y_",
-			"description": "Y-axis offset for labels",
+			"description": "Vertical offset for text labels on the PCA plot.",
 			"type": "text",
 			"value_type": "string",
 			"default_value": "2"
 		},
+		{
+			"id": "log_transform_id",
+			"category": "7Rr6IxOMDucKMImp",
+			"name": "Log transform counts",
+			"param_name": "log_transform",
+			"description": "Apply log(x + pseudocount) to sample count columns before PCA. Use this for count-like data such as raw, clean, filt, or CPM-like counts; leave FALSE for already normalized/log-scale or batch-corrected values to avoid double transformation.",
+			"type": "list",
+			"value_type": "string",
+			"default_value": "FALSE",
+			"extra_data": [
+				"TRUE",
+				"FALSE"
+			]
+		},
 		{
 			"id": "interactive_plots_id",
 			"category": "FvI4Z2eb9sjL47Jt",
 			"name": "Interactive plots",
 			"param_name": "interactive_plots",
-			"description": "Whether to create interactive plots",
+			"description": "Set to TRUE to make the PCA plot interactive with plotly.",
 			"type": "list",
 			"value_type": "string",
 			"default_value": "FALSE",
@@ -202,7 +213,7 @@
 			"category": "FvI4Z2eb9sjL47Jt",
 			"name": "Color values",
 			"param_name": "color_values",
-			"description": "Comma-separated group colors. Defaults to the MOSuite palette.",
+			"description": "Vector of colors as hex values or names recognized by R. Unnamed colors are assigned by factor level order when the grouping column is a factor; otherwise, they follow the order in which groups first appear in the metadata column.",
 			"help_text": "Use color names or hex codes. Supplied colors are used first; if there are more groups than colors, additional colors are generated from the MOSuite palette, with random colors only if that palette is too short.",
 			"type": "text",
 			"value_type": "string",

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Development version
 
+- Sync Code Ocean app panel parameter descriptions with MOSuite package documentation for MOSuite v0.4.1 (#7, @phoman14).
 - Align the PCA color defaults with MOSuite package defaults (#2, @phoman14).
 - Document that color palettes fall back to random colors only when too few colors are provided (#2, @phoman14).
 - Improved the Code Ocean parameter UI for the plot pca 2D capsule (#1, @phoman14).

code/main.R

@@ -62,18 +62,18 @@ parser$add_argument(
   default = "top",
   help = "Position of the legend"
 )
+parser$add_argument(
+  "--legend_font_size",
+  type = "double",
+  default = NULL,
+  help = "Font size for legend text"
+)
 parser$add_argument(
   "--point_size",
   type = "double",
   default = 3,
   help = "Size of points in plot"
 )
-parser$add_argument(
-  "--add_label",
-  type = "logical",
-  default = TRUE,
-  help = "Whether to add labels to points"
-)
 parser$add_argument(
   "--label_font_size",
   type = "double",
@@ -92,6 +92,12 @@ parser$add_argument(
   default = 2,
   help = "Y-axis offset for labels"
 )
+parser$add_argument(
+  "--log_transform",
+  type = "logical",
+  default = FALSE,
+  help = "Log-transform counts before PCA"
+)
 parser$add_argument(
   "--interactive_plots",
   type = "logical",
@@ -124,11 +130,12 @@ plot_pca_2d(
   group_colname = args$group_colname,
   label_colname = args$label_colname,
   legend_position = args$legend_position,
+  legend_font_size = args$legend_font_size,
   point_size = args$point_size,
-  add_label = args$add_label,
   label_font_size = args$label_font_size,
   label_offset_x_ = args$label_offset_x_,
   label_offset_y_ = args$label_offset_y_,
+  log_transform = args$log_transform,
   interactive_plots = args$interactive_plots,
   color_values = parse_optional_vector(args$color_values)
 )

tests/testthat/test-main.R

@@ -14,42 +14,18 @@ test_that("Code Ocean panel uses named parameters accepted by main.R", {
   )
 })
 
-test_that("2D PCA capsule keeps expected PCA parameter contract", {
+test_that("2D PCA capsule keeps expected PCA parameter defaults", {
   main_lines <- read_repo_file("code", "main.R")
   panel_lines <- read_repo_file(".codeocean", "app-panel.json")
 
-  shared_pca_args <- c(
-    "count_type",
-    "sub_count_type",
-    "feature_id_colname",
-    "sample_id_colname",
-    "samples_to_rename",
-    "group_colname",
-    "label_colname",
-    "principal_components",
-    "point_size",
-    "label_font_size",
-    "color_values"
-  )
-  two_dimensional_args <- c(
-    "legend_position",
-    "add_label",
-    "label_offset_x_",
-    "label_offset_y_",
-    "interactive_plots"
-  )
-
-  expect_same_values(
-    extract_main_arguments(main_lines),
-    c(shared_pca_args, two_dimensional_args),
-    info = "2D PCA main.R should expose shared PCA args plus 2D-specific controls"
-  )
   expect_match(paste(main_lines, collapse = "\n"), "plot_pca_2d\\(")
   expect_equal(
     extract_panel_default(panel_lines, "principal_components"),
     "1,2"
   )
-  expect_equal(extract_panel_default(panel_lines, "add_label"), "TRUE")
+  expect_equal(extract_panel_default(panel_lines, "label_colname"), "Label")
+  expect_true(is.na(extract_panel_default(panel_lines, "legend_font_size")))
+  expect_equal(extract_panel_default(panel_lines, "log_transform"), "FALSE")
   expect_equal(extract_panel_default(panel_lines, "interactive_plots"), "FALSE")
 })