Merge pull request nextstrain#1321 from nextstrain/bug-narratives-zoom-to-selected

Zoom to selected is stored as a URL query

Author: jameshadfield

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+* Added a `treeZoom=selected` query to load trees at the same zoom level after the "zoom to selected" button has been pressed, where applicable. See [the view settings docs](https://docs.nextstrain.org/projects/auspice/en/latest/advanced-functionality/view-settings.html) for more details. ([#1321](https://github.com/nextstrain/auspice/pull/1321))
+
 ## version 2.63.1 - 2025/06/04
 
 

docs/advanced-functionality/view-settings.rst

@@ -56,6 +56,12 @@ These are exported as the (optional) property of the dataset JSON ``meta.display
 +---------------------------+-----------------------------------------------------------------------+----------------------------------------------------+
 | ``label``                 | Labelled branch that tree starts zoomed to                            | "Sublineage:J" or "clade:2a.3a"                    |
 +---------------------------+-----------------------------------------------------------------------+----------------------------------------------------+
+| ``treeZoom``              | Controls how a tree is initially zoomed (see note below)              | "treeZoom=selected"                                |
++---------------------------+-----------------------------------------------------------------------+----------------------------------------------------+
+
+
+* The `treeZoom=selected` query is only applicable in certain circumstances and acts as if we had applied all other view settings and then clicked the "zoom to selected" button. The behaviour of the "zoom to selected" button can differ depending on the current zoom level of the tree, and the URL query will only be set if the same zoom level is obtaibavle if you click the button from a fully zoomed out state; see [this GitHub thread for more details](https://github.com/nextstrain/auspice/pull/1321#issuecomment-2914923800). Finally, if a `label` query is in the URL then that will be used instead as it has higher specificity.
+
 
 Certain other properties on the JSON's ``meta`` dictionary also affect the view settings.
 See the `JSON schema <https://github.com/nextstrain/augur/blob/master/augur/data/schema-export-v2.json>`__ for more details.

narratives/test_simultaneous-tree-updates.md

@@ -5,36 +5,43 @@ authors:
 authorLinks:
   - https://twitter.com/hamesjadfield
 affiliations: "Fred Hutch"
-dataset: "http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree"
+dataset: "http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&c=num_date"
 date: June 2020
 abstract: "A narrative to explore simultaneous changes to tree state. The aim is both to reveal what's possible, and to prevent future regressions via automated testing."
 ---
 
 
-# [P1: Change coloring to sampling date](http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&c=num_date&branchLabel=aa)
+# [P1: Change coloring to clade](http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&branchLabel=aa)
 
-Check that both the branches and tips update.
+Check that both the branches and tips update. (The clade coloring is the default, so this slide removes the previous `c=num_date` query)
 
 The clade labels should now show selected amino acids (with the selecting being done by auspice).
 
-# [P2: Zoom into clade 3C.2a1b.2a.2](http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&c=num_date&label=clade:3C.2a1b.2a.2&branchLabel=aa&showBranchLabels=all)
+# [P2: Zoom in via filtering & "zoom-to-selected"](http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&branchLabel=aa&f_clade_membership=3C.2a1b.2a.1,3C.2a1b.2a.2&treeZoom=selected)
 
-We simultaneously zoom into clade 3C.2a1b.2a.2 (top right section of tree) and show _all_ AA mutations as branch labels.
-If you go to the previous slide the aa mutation labels should revert to only showing a subset.
+We add two clade filters: "3C.2a1b.2a.1" & "3C.2a1b.2a.2" and the URL query `treeZoom=selected` which zooms into their CA
+(which does not have its own branch label)
+
+
+# [P3: Zoom in further](http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&c=num_date&label=clade:3C.2a1b.2a.2&branchLabel=aa&showBranchLabels=all)
+
+We simultaneously zoom into clade 3C.2a1b.2a.2 (top right section) and show _all_ AA mutations as branch labels.
+If you go to the previous slide(s) the aa mutation labels should revert to only showing a subset.
+
+# [P4: Zoom out to clade 3C.2a1b.2 _and_ change color](http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&label=clade:3C.2a1b.2)
 
-# [P3: Zoom out to clade 3C.2a1b.2 _and_ change color](http://localhost:4000/flu/seasonal/h3n2/ha/3y?d=tree&label=clade:3C.2a1b.2)
 Check that the coloring of the branches and tips update as we zoom out (slightly).
 
 The coloring should be back to the default (clade), and so should the branch labels (clade also).
 
-# [P4: Lots of simultaneous changes](http://localhost:4000/flu/seasonal/h3n2/ha/3y?c=lbi&d=tree&dmin=2017-01-01&f_region=North%20America&label=clade:3C.2a&m=div)
+# [P5: Lots of simultaneous changes](http://localhost:4000/flu/seasonal/h3n2/ha/3y?c=lbi&d=tree&dmin=2017-01-01&f_region=North%20America&label=clade:3C.2a&m=div)
 * Zoomed out to near the root (clade 3C.2a)
 * Changed the horizontal scale to divergence
 * Changed the color-by to LBI (and legend should be open)
-* Filtered to North American Samples (i.e. the majority of tips are not visible).
+* Kept the North American region filter (i.e. the majority of tips are not visible).
 * Time slice excludes pre-2017 samples (note that we don't have the grey overlay here since the axis is divergence)
 
-# [P5: Layout change (and others)](http://localhost:4000/flu/seasonal/h3n2/ha/3y?branchLabel=none&d=tree&l=radial&m=div)
+# [P6: Layout change (and others)](http://localhost:4000/flu/seasonal/h3n2/ha/3y?branchLabel=none&d=tree&l=radial&m=div)
 Underneath, this uses a different set of d3 calls where instead of transitioning all elements (branches, tips etc), which is too slow, we do a "in-parts" update: we hide the branches, transition the tips, then redraw the branches in their new position.
 This slide should
 * switch to radial view

src/actions/recomputeReduxState.js

@@ -3,7 +3,7 @@ import { cloneDeep, isEqualWith } from 'lodash';
 import { numericToCalendar, calendarToNumeric } from "../util/dateHelpers";
 import { reallySmallNumber, twoColumnBreakpoint, defaultColorBy, defaultGeoResolution, defaultDateRange, nucleotide_gene, strainSymbol, genotypeSymbol } from "../util/globals";
 import { calcBrowserDimensionsInitialState } from "../reducers/browserDimensions";
-import { getIdxMatchingLabel, calculateVisiblityAndBranchThickness } from "../util/treeVisibilityHelpers";
+import { getIdxMatchingLabel, calculateVisiblityAndBranchThickness, getFilteredAndIdxOfFilteredRoot } from "../util/treeVisibilityHelpers";
 import { constructVisibleTipLookupBetweenTrees } from "../util/treeTangleHelpers";
 import { getDefaultControlsState, shouldDisplayTemporalConfidence } from "../reducers/controls";
 import { getDefaultFrequenciesState } from "../reducers/frequencies";
@@ -656,6 +656,11 @@ const checkAndCorrectErrorsInState = (state, metadata, genomeMap, query, tree, v
     }
   }
 
+  /* Currently the (rather unique) treeZoom query can only have the value 'selected' */
+  if (query.treeZoom && query.treeZoom!=='selected') {
+    delete query.treeZoom;
+  }
+
   /* temporalConfidence */
   if (
     shouldDisplayTemporalConfidence(state.temporalConfidence.exists, state.distanceMeasure, state.layout)
@@ -756,25 +761,29 @@ const checkAndCorrectErrorsInState = (state, metadata, genomeMap, query, tree, v
 const modifyTreeStateVisAndBranchThickness = (oldState, displayDefaults, query, controlsState, dispatch) => {
   /* calculate the index of the (in-view) root note, which depends on any selected zoom */
   let newIdxRoot = oldState.idxOfInViewRootNode;
-  let cladeSelectedIdx = 0; // default to tree root
   if (query.label) {
     const [labelName, labelValue] = parseLabel(query.label)
     const idx = getIdxMatchingLabel(oldState.nodes, labelName, labelValue, dispatch);
     if (idx === null) {
       delete query.label;
     } else {
-      cladeSelectedIdx = idx;
+      newIdxRoot = applyInViewNodesToTree(idx, oldState);
     }
+  } else if (query.treeZoom==="selected") {
+    // zoom to selected requires filters to be applied to tree to calculate the appropriate root
+    // Note that these are re-calculated by `calculateVisiblityAndBranchThickness`
+    const {idxOfFilteredRoot} = getFilteredAndIdxOfFilteredRoot(oldState, controlsState, oldState.nodes.map(() => true));
+    newIdxRoot = applyInViewNodesToTree(idxOfFilteredRoot, oldState);
+    if (!idxOfFilteredRoot) delete query.treeZoom;
   } else if (displayDefaults.label) {
     const [labelName, labelValue] = parseLabel(displayDefaults.label)
     const idx = getIdxMatchingLabel(oldState.nodes, labelName, labelValue, dispatch);
     if (idx === null) {
       delete displayDefaults.label;
     } else {
-      cladeSelectedIdx = idx;
+      newIdxRoot = applyInViewNodesToTree(idx, oldState);
     }
   }
-  newIdxRoot = applyInViewNodesToTree(cladeSelectedIdx, oldState);
 
   /* calculate new branch thicknesses & visibility, as this depends on the root note */
   const visAndThicknessData = calculateVisiblityAndBranchThickness(

src/middleware/changeURL.js

@@ -5,6 +5,7 @@ import { urlQueryLabel } from "../util/treeVisibilityHelpers";
 import { shouldDisplayTemporalConfidence } from "../reducers/controls";
 import { genotypeSymbol, nucleotide_gene, strainSymbol } from "../util/globals";
 import { encodeGenotypeFilters, decodeColorByGenotype, isColorByGenotype } from "../util/getGenotype";
+import { getFilteredAndIdxOfFilteredRoot } from "../util/treeVisibilityHelpers";
 import { removeInvalidMeasurementsFilterQuery } from "../actions/measurements";
 
 export const strainSymbolUrlString = "__strain__";
@@ -197,6 +198,24 @@ export const changeURLMiddleware = (store) => (next) => (action) => {
     case types.UPDATE_VISIBILITY_AND_BRANCH_THICKNESS: {
       // NOTE: `idxOfInViewRootNode` refers to the left tree only (if 2 trees displayed)
       query.label = urlQueryLabel(state.tree.nodes[action.idxOfInViewRootNode], state.tree.availableBranchLabels)
+      /* The "zoom to selected" button will zoom to the `idxOfFilteredRoot` (i.e. its behaviour depends on the selected
+      filters). If the LHS tree is zoomed to this node, either by chance or by having clicked on the button, then set
+      this as query. Any other zoom/filtering action will remove it */
+      if (
+        /* if there's a label then don't use zoom-to-selected as the label is more specific */
+        query.label===undefined &&
+        /* The "zoom to selected" button will zoom us to the idxOfFilteredRoot, so check we're
+        there - either because we pressed the button or because we clicked that branch */
+        action.idxOfFilteredRoot===action.idxOfInViewRootNode &&
+        /* Ensure the filtered tips (across the entire tree) are _all_ downstream of the current zoomed node
+        i.e. the CA of filtered tips when the entire tree's in view is the same as the current zoom node. See
+        <https://github.com/nextstrain/auspice/pull/1321#issuecomment-2914923800> for more context. */
+        action.idxOfFilteredRoot===getFilteredAndIdxOfFilteredRoot(state.tree, state.controls, state.tree.nodes.map(() => true)).idxOfFilteredRoot
+      ) {
+        query.treeZoom="selected"; // using a string value allows for future expansion of functionality
+      } else {
+        query.treeZoom = undefined
+      }
       break;
     }
     case types.MAP_ANIMATION_PLAY_PAUSE_BUTTON:

src/util/treeVisibilityHelpers.js

@@ -172,7 +172,7 @@ const getInView = (tree) => {
  * - controls.filters (redux) is a dict of trait name -> values
  * - filters (in this code) is a list of filters to apply
  *   e.g. [{trait: "country", values: [...]}, ...] */
-const getFilteredAndIdxOfFilteredRoot = (tree, controls, inView) => {
+export const getFilteredAndIdxOfFilteredRoot = (tree, controls, inView) => {
   if (!tree.nodes) {
     console.error("getFiltered() ran without tree.nodes");
     return null;