Skip to content
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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")
Expand All @@ -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)".
*/
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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)}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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()
Expand Down
Loading