diff --git a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDesc.scala b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDesc.scala index c433e198bca..8ace6e5677a 100644 --- a/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDesc.scala +++ b/common/workflow-operator/src/main/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDesc.scala @@ -27,6 +27,7 @@ import org.apache.texera.amber.operator.visualization.PlotlyStandaloneCode import org.apache.texera.amber.operator.visualization.PythonVisualizationOpDesc import org.apache.texera.amber.operator.metadata.annotations.{AutofillAttributeName, SampleColumn} import org.apache.texera.amber.operator.metadata.{OperatorGroupConstants, OperatorInfo} +import org.apache.texera.amber.pybuilder.PythonTemplateBuilder import org.apache.texera.amber.pybuilder.PythonTemplateBuilder.pyStringLiteral import javax.validation.constraints.NotNull @@ -67,6 +68,14 @@ class VolcanoPlotOpDesc extends PythonVisualizationOpDesc with PlotlyStandaloneC @NotNull(message = "P-Value Column cannot be empty") var pvalueColumn: EncodableString = "" + @JsonProperty(required = false) + @JsonSchemaTitle("Hover column") + @JsonPropertyDescription( + "Column value to display when a dot is hovered over; leave empty for the first column" + ) + @AutofillAttributeName + var hoverName: EncodableString = "" + @JsonProperty(required = false) @JsonSchemaTitle("Title") @JsonPropertyDescription("The figure title; leave empty for Volcano Plot") @@ -91,6 +100,39 @@ class VolcanoPlotOpDesc extends PythonVisualizationOpDesc with PlotlyStandaloneC operatorGroupName = OperatorGroupConstants.VISUALIZATION_SCIENTIFIC_GROUP ) + /** An empty or blank hover column keeps the first column, which is what saved + * workflows show. One rule for both code paths, so they cannot disagree. + */ + private def hoverColumnSet: Boolean = hoverName.trim.nonEmpty + + private def hoverColumn: PythonTemplateBuilder = + if (hoverColumnSet) pyb"$hoverName" else pyb"table.columns[0]" + + /** A set hover column that the input lacks gets the operator's error page, like the + * two required columns, instead of the ValueError plotly would raise. + */ + private def hoverColumnCheck: PythonTemplateBuilder = + if (hoverColumnSet) + pyb"""if $hoverName not in table.columns: + | yield {"html-content": self.render_error("Missing hover column in table.")} + | return + |""" + else pyb"" + + // The exported script's twins of the two helpers above, with the column name as a + // Python literal rather than decoded. The check is one more `elif` in the script's + // chain, so it ends with its own newline and the template puts `else:` right after it. + private def standaloneHoverColumn: String = + if (hoverColumnSet) pyStringLiteral(hoverName) else "table.columns[0]" + + private def standaloneHoverColumnCheck: String = + if (hoverColumnSet) + s"""elif ${pyStringLiteral(hoverName)} not in in1df.columns: + | with open(outputHtml, "w", encoding="utf-8") as output: + | output.write(render_error("Missing hover column in table.")) + |""".stripMargin + else "" + /** The y column is named after the selected p-value column, so a figure drawn * from an adjusted column says so instead of always reading "-log10(pvalue)". */ @@ -122,7 +164,7 @@ class VolcanoPlotOpDesc extends PythonVisualizationOpDesc with PlotlyStandaloneC | if $pvalueColumn not in table.columns or $effectColumn not in table.columns: | yield {"html-content": self.render_error("Missing required columns in table.")} | return - | + | $hoverColumnCheck | # Filter out non-positive p-values to avoid math errors | table = table[table[$pvalueColumn] > 0] | if table.empty: @@ -135,7 +177,7 @@ class VolcanoPlotOpDesc extends PythonVisualizationOpDesc with PlotlyStandaloneC | table, | x=$effectColumn, | y=$yColumn, - | hover_name=table.columns[0], + | hover_name=$hoverColumn, | color=$effectColumn, | color_continuous_scale="RdBu", | title=$titleText @@ -168,7 +210,7 @@ class VolcanoPlotOpDesc extends PythonVisualizationOpDesc with PlotlyStandaloneC |elif $pvalueLit not in in1df.columns or $effectLit not in in1df.columns: | with open(outputHtml, "w", encoding="utf-8") as output: | output.write(render_error("Missing required columns in table.")) - |else: + |${standaloneHoverColumnCheck}else: | table = in1df[in1df[$pvalueLit] > 0].copy() | if table.empty: | with open(outputHtml, "w", encoding="utf-8") as output: @@ -179,7 +221,7 @@ class VolcanoPlotOpDesc extends PythonVisualizationOpDesc with PlotlyStandaloneC | table, | x=$effectLit, | y=$yLit, - | hover_name=table.columns[0], + | hover_name=$standaloneHoverColumn, | color=$effectLit, | color_continuous_scale="RdBu", | title=${pyStringLiteral(titleText)} diff --git a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDescSpec.scala b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDescSpec.scala index 79faa0e4ed8..302ff8f2d03 100644 --- a/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDescSpec.scala +++ b/common/workflow-operator/src/test/scala/org/apache/texera/amber/operator/visualization/volcanoPlot/VolcanoPlotOpDescSpec.scala @@ -80,6 +80,53 @@ class VolcanoPlotOpDescSpec extends AnyFlatSpec with Matchers { decodeOccurrences should be >= 2 } + private def decodeSites(code: String): Int = + "decode_python_template".r.findAllIn(code).length + + it should "keep the first column as the hover label when no hover column is set" in { + val code = configured.generatePythonCode() + code should include("hover_name=table.columns[0],") + // An empty field adds no decode site of its own, and nothing to check for. + code should not include "hover_name=self.decode_python_template(" + code should not include "Missing hover column" + } + + it should "answer a set hover column that the table lacks with the operator's error page" in { + // Like the two required columns, and unlike plotly's uncaught ValueError. + val op = configured + op.hoverName = "gene" + val code = op.generatePythonCode() + code should include(s"if ${decoded("gene")} not in table.columns:") + code should include("""self.render_error("Missing hover column in table.")""") + } + + it should "treat a whitespace-only hover column as empty" in { + Seq(" ", "\t", " \n ").foreach { blank => + val op = configured + op.hoverName = blank + op.generatePythonCode() shouldBe configured.generatePythonCode() + } + } + + it should "use the configured hover column instead of the first column" in { + val op = configured + op.hoverName = "gene" + val code = op.generatePythonCode() + code should include(s"hover_name=${decoded("gene")},") + code should not include "hover_name=table.columns[0]" + // Exactly two decode sites more than the default: the presence check and the + // hover_name argument, both naming the hover column. + decodeSites(code) shouldBe decodeSites(configured.generatePythonCode()) + 2 + } + + it should "route a hover column with quotes and non-ASCII text through the decoder" in { + val op = configured + op.hoverName = "HOVER_SENT \"gene\" 基因" + val code = op.generatePythonCode() + code should include(s"hover_name=${decoded(op.hoverName)},") + code should not include "HOVER_SENT" + } + it should "name the y column and its axis after the selected p-value column" in { // The y axis used to read "-log10(pvalue)" whatever column was chosen; a // figure drawn from an adjusted column must say so. @@ -156,7 +203,52 @@ class VolcanoPlotOpDescSpec extends AnyFlatSpec with Matchers { saved.generatePythonCode() shouldBe configured.generatePythonCode() } - "VolcanoPlotOpDesc.generateStandaloneCode" should "name the y column and its axis after the selected p-value column" in { + "VolcanoPlotOpDesc.generateStandaloneCode" should "keep the first column as the hover label when no hover column is set" in { + val code = configured.generateStandaloneCode() + code should include("hover_name=table.columns[0],") + code should not include "Missing hover column" + } + + it should "use the configured hover column as a literal and check that the table has it" in { + val op = configured + op.hoverName = "gene" + val code = op.generateStandaloneCode() + code should include("""hover_name="gene",""") + code should not include "hover_name=table.columns[0]" + // One more branch of the script's column checks, before the row filter and + // right before the drawing branch, so a missing hover column gets the error + // page and not plotly's ValueError. + code should include( + """ output.write(render_error("Missing required columns in table.")) + |elif "gene" not in in1df.columns: + | with open(outputHtml, "w", encoding="utf-8") as output: + | output.write(render_error("Missing hover column in table.")) + |else:""".stripMargin + ) + } + + it should "escape a hover column with quotes or a backslash rather than decode it" in { + // The export has no decoder, so the name itself is in the script: a quote or a + // backslash must come out escaped, or the literal would end early. + val op = configured + op.hoverName = "HOVER_SENT \"gene\" 基因" + val code = op.generateStandaloneCode() + code should include("hover_name=\"HOVER_SENT \\\"gene\\\" 基因\",") + code should include("elif \"HOVER_SENT \\\"gene\\\" 基因\" not in in1df.columns:") + code should not include "decode_python_template" + op.hoverName = "gene\\id" + op.generateStandaloneCode() should include("hover_name=\"gene\\\\id\",") + } + + it should "treat a whitespace-only hover column as empty" in { + Seq(" ", "\t", " \n ").foreach { blank => + val op = configured + op.hoverName = blank + op.generateStandaloneCode() shouldBe configured.generateStandaloneCode() + } + } + + it should "name the y column and its axis after the selected p-value column" in { val op = configured op.pvalueColumn = "padj" val code = op.generateStandaloneCode()