fix(quickview): address some inconsistent and outdated wording; turn on sorting in file browser

README.md

@@ -7,37 +7,41 @@
 [![Conda Version](https://img.shields.io/conda/vn/conda-forge/e3sm-quickview.svg)](https://anaconda.org/conda-forge/e3sm-quickview)
 [![](https://img.shields.io/badge/Conda%20Forge%20Repo-blue)](https://github.com/conda-forge/e3sm-quickview-feedstock)
 
+<!-- #region quickview-intro -->
 **QuickView** is an open-source, interactive visualization
 tool designed to help Earth system modelers take a quick look at
 a collection of physical quantities in their simulation files.
-The physical quantities are presented as contour plots on global or regional maps.
-
-Currently, QuickView only supports the cubed-sphere meshes
-used by the atmosphere component of the
-[Energy Exascale Earth System Model (E3SM)](https://e3sm.org),
-i.e., the `ne*np4` GLL grids and the `ne*pg2` "physics" grids,
-but extensions to other meshes are underway.
-
-QuickView's Python- and [trame](https://www.kitware.com/trame/)-based User Interface (UI)
-provides intuitive access to [ParaView](https://www.paraview.org/)'s powerful
-analysis and visualization capabilities without requiring a steep learning curve.
-
-
-![Application](https://raw.githubusercontent.com/Kitware/QuickView/master/docs/public/website_banner.png)
-
+The physical quantities are presented in the form of contour plots on global or regional maps.
+Currently, QuickView supports cubed-sphere grids
+consisting of either Gauss-Lobatto-Legendre (GLL) nodes (i.e., the `ne*np4` grids)
+or finite-volume grid cells (`ne*pg2`, `ne*pg3`, etc.).
+
+Under the hood, [ParaView](https://www.paraview.org/) and
+[VTK](https://vtk.org/) supply the data-processing and graphics capabilities,
+while [trame](https://www.kitware.com/trame/), a Python package,
+is used to build a browser-based graphical User Interface (UI)
+to provide intuitive and task-focused controls of the visualization
+so that users do not need to operate ParaView or VTK themselves.
+<!-- #endregion quickview-intro -->
+
+![QuickView UI](https://raw.githubusercontent.com/Kitware/QuickView/master/docs/public/website_banner.png)
+
+<!-- #region quickview-key-features -->
 ## Key Features
 
 - Intuitive, minimalist interface tailored for Earth system modeling.
 - Multi-variable visualization.
 - Persistent sessions—pick up where you left off.
-- Support for EAM v2, v3, and upcoming v4 output formats
-  as well as the E3SM land model ELM's input and output files
-  on `ne*np4` and `ne*pg2` grids.
+- Currently supporting cubed-sphere grids in a variety of configurations.
+  Examples can be found in the [visualization gallery](https://kitware.github.io/QuickView/gallery/).
+<!-- #endregion quickview-key-features -->
 
 ## Getting Started 
 
 See our [documentation page](https://kitware.github.io/QuickView/guides/quickview/getting_started.html).
 
+<!-- #region quickview-project -->
+
 ## Project Background
 
 QuickView is developed by [Kitware, Inc.](https://www.kitware.com/) in
@@ -48,12 +52,16 @@ U.S. Department of Energy's
 and
 [BER](https://www.energy.gov/science/ber/biological-and-environmental-research)
 programs via [SciDAC](https://www.scidac.gov/).
+The development of QuickView used resources of the National Energy Research Scientific Computing Center
+([NERSC](https://www.nersc.gov/)), a U.S. Department of Energy User Facility.
 
 ### Contributors
 
 - **Lead Developer**: Abhishek Yenpure (now at NVIDIA) for version 1; [Sebastien Jourdain](https://www.kitware.com/sebastien-jourdain/) ([Kitware, Inc.](https://www.kitware.com/)) from version 2 onwards.
 - **Key Contributors**: Berk Geveci, Patrick O'Leary, Dan Lipsa, Will Dunklin (Kitware, Inc.); Hui Wan, Kai Zhang (PNNL)
 
+<!-- #endregion quickview-project -->
+
 ## License
 
 Apache Software License - see [LICENSE](LICENSE) file for details.

docs/guides/quickview/file_selection.md

@@ -13,10 +13,17 @@ When QuickView is launched using a shell command or the desktop bundle,
 or when the user clicks the "File Loading" icon on the toolbar,
 a dialogue window like the screenshot below is brought up.
 The user is expected to select a connectivity file and a simulation data file
-from the file browser in this window.
+using the file browser or the text boxes in this window.
 
 ![File loading window](./screenshots/file_loading_dialogue.png){ width="100%", align=center }
 
+### Selecting files using the file browser
+
+Click the **Name**, **Size**, or **Date modified** column heading to sort the entries
+by that column. Repeated clicks cycle through ascending order, descending order,
+and the original order (directories first, then file groups, then individual files,
+with each group sorted by name).
+
 The user can single-click a file name and then click the "simulation" or "connectivity"
 button in the bottom-left corner to clarify file type.
 
@@ -26,6 +33,14 @@ recognized as a connectivity file.
 Double-clicking a filename not starting with "connectivity" makes
 it recognized as a simulation file.
 
+### Selecting files by direct text input
+
+If the needed files are many directories away from the directory shown in the file browser,
+the user can avoid tedious navigation by pasting full paths, including filenames,
+into the **Simulation File** and **Connectivity File** text boxes below the browser.
+
+### Loading the selected files
+
 After both connectivity and simulation files are selected,
 the originally pale-blue `Load Files` button in the bottom-right corner
 changes to bright blue. A single click starts file loading.

docs/guides/quickview/index.md

@@ -2,30 +2,7 @@
 
 ![QuickView icon](/public/logos/quickview-icon-only.png){ width="12%", align=right }
 
-**QuickView** is an open-source, interactive visualization
-tool designed to help Earth system modelers take a quick look at
-a collection of physical quantities in their simulation files.
-The physical quantities are presented in the form of contour plots on global or regional maps.
-Currently, QuickView supports cubed-sphere grids
-consisting of either Gauss-Lobatto-Legendre (GLL) nodes (i.e., the `ne*np4` grids)
-or finite-volume grid cells (`ne*pg2`, `ne*pg3`, etc.).
-
-Under the hood, [ParaView](https://www.paraview.org/) and
-[VTK](https://vtk.org/) supply the data-processing and graphics capabilities,
-while [trame](https://www.kitware.com/trame/), a Python package,
-is used to build a browser-based graphical User Interface (UI)
-to provide intuitive and task-focused controls of the visualization
-so that users do not need to operate ParaView or VTK themselves.
-
-Under the hood, [ParaView](https://www.paraview.org/) and
-[VTK](https://vtk.org/) supply the data-processing and graphics capabilities,
-while [trame](https://www.kitware.com/trame/), a Python framework for
-interactive applications, connects these capabilities to a browser-based
-graphical user interface. Trame provides the interface controls,
-communicates user selections to the visualization code,
-and delivers updated images to the display.
-Together, these tools let QuickView provide intuitive, task-focused controls
-for exploring model output without requiring users to operate ParaView or VTK themselves.
+<!--@include: ../../../README.md#quickview-intro-->
 
 Useful resources: see [linked page](./getting_started).
 
@@ -54,37 +31,6 @@ similarities or distinctions. Compared to earlier and widely used tools like
 [ncvis](https://github.com/SEATStandards/ncvis), QuickView has an emphasis on
 multivariate visualization.
 
-## Key Features
-
-- Intuitive, minimalist interface tailored for Earth system modeling.
-- Multi-variable visualization.
-- Persistent sessions—pick up where you left off.
-- Currently supporting cubed-sphere grids in a variety of configurations
-  and representations. Examples can be found in the [visualization gallery](/gallery/index).
-
-## Project Background
-
-The lead developer of QuickView version 1 was Abhishek Yenpure.
-The lead developer from version 2 onwards is
-[Sebastien Jourdain](https://www.kitware.com/sebastien-jourdain/).
-Other key contributors include
-Patrick O'Leary, Berk Geveci, Dan Lipsa, and Will Dunklin at
-[Kitware](https://www.kitware.com/), and
-Hui Wan and Kai Zhang at
-[Pacific Northwest National Laboratory](https://www.pnnl.gov/atmospheric-climate-and-earth-sciences-division).
-
-QuickView is a product of an interdisciplinary collaboration supported by
-the U.S. Department of Energy Office of Science’s
-[Advanced Scientific Computing Research (ASCR)](https://www.energy.gov/science/ascr/advanced-scientific-computing-research)
-and
-[Biological and Environmental Research (BER)](https://www.energy.gov/science/ber/biological-and-environmental-research)
-via the
-[Scientific Discovery through Advanced Computing (SciDAC](https://www.scidac.gov/))
-program.
-
-The development of QuickView used resources of the National Energy Research Scientific Computing Center
-([NERSC](https://www.nersc.gov/)), a U.S. Department of Energy User Facility.
-
-----
+<!--@include: ../../../README.md#quickview-key-features-->
 
-![SciDAC, Kitware, and PNNL](/logos/SciDAC-Kitware-PNNL.png){ width="55%", align=center }
+<!--@include: ../../../README.md#quickview-project-->

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "e3sm-quickview"
 version = "2.10.5"
-description = "An application to explore/analyze data for atmosphere component for E3SM"
+description = "An application to explore/analyze Earth system simulation data"
 authors = [
     {name = "Kitware Inc."},
 ]

src/e3sm_quickview/components/doc.py

@@ -189,14 +189,8 @@ def __init__(self):
                 tool designed to help Earth system modelers take a quick look at
                 a collection of physical quantities in their simulation files.
                 The physical quantities are presented in the form of global or regional maps.
-                Currently, QuickView supports only the cubed-sphere "physics" grids,
-                i.e., the ne*pg2 meshes used by the atmosphere component of the
-                {Link("Energy Exascale Earth System Model (E3SM)", "https://e3sm.org/")},
-                but extensions to other grids are underway.
-                QuickView's Python and {Link("trame", "https://www.kitware.com/trame/")}-based
-                graphical User Interface (UI) provides the users with intuitive access to
-                {Link("ParaView", "https://www.paraview.org/")}'s powerful analysis
-                and visualization capabilities without requiring a steep learning curve.
+                Sample visualizations can be found in the
+                {Link("online gallery", "https://kitware.github.io/QuickView/gallery/")}.
                 A detailed {Bold("User's Guide")} can be found through
                 {Link("this link", "https://kitware.github.io/QuickView/guides/quickview/")}.
                 {Bold("Bug reports")} and feature requests can be submitted on
@@ -314,7 +308,7 @@ def __init__(self):
                                 v3.VHotkey(keys="m", variant="contained", inline=True)
                         with v3.VListItem(subtitle="Spherical"):
                             with v3.Template(v_slot_append="True"):
-                                v3.VHotkey(keys="z", variant="contained", inline=True)
+                                v3.VHotkey(keys="n", variant="contained", inline=True)
 
                     v3.VDivider(classes="my-4")
 
@@ -354,7 +348,7 @@ def __init__(self):
                 through a partnership between
                 the {
                 Link(
-                    "Advanced Scientific Computing Reaserch (ASCR)",
+                    "Advanced Scientific Computing Research (ASCR)",
                     "https://www.energy.gov/science/ascr/advanced-scientific-computing-research",
                 )
             } program and

src/e3sm_quickview/components/file_browser.py

@@ -12,9 +12,9 @@
 FILE = dict(icon="mdi-file-document-outline", type="file")
 
 HEADERS = [
-    {"title": "Name", "align": "start", "key": "name", "sortable": False},
-    {"title": "Size", "align": "end", "key": "size", "sortable": False},
-    {"title": "Date", "align": "end", "key": "modified", "sortable": False},
+    {"title": "Name", "align": "start", "key": "name", "sortable": True},
+    {"title": "Size", "align": "end", "key": "size", "sortable": True},
+    {"title": "Date modified", "align": "end", "key": "modified", "sortable": True},
 ]
 
 
@@ -132,7 +132,7 @@ def listing(self):
 
                 g_map[g_name]["size"] += stats.st_size
                 g_map[g_name]["files"].append(file_name)
-                # Many need to sort files???
+                # May need to sort files.
             else:
                 # File
                 files.append(
@@ -290,7 +290,7 @@ def ui(self):
         with v3.VCard(rounded="lg"):
             with v3.VCardTitle("File loading", classes="d-flex align-center px-3"):
                 v3.VSpacer()
-                with v3.VTooltip(text="Go to launched directory"):
+                with v3.VTooltip(text="Return to starting directory"):
                     with v3.Template(v_slot_activator="{ props }"):
                         v3.VBtn(
                             v_bind="props",
@@ -312,7 +312,7 @@ def ui(self):
                     v_model=self.name("filter"),
                     hide_details=True,
                     color="primary",
-                    placeholder="filter",
+                    placeholder="Filter by name",
                     density="compact",
                     variant="outlined",
                     classes="ml-2",
@@ -382,8 +382,7 @@ def ui(self):
                     v_model=(self.name("data_simulation"), ""),
                     density="compact",
                     variant="outlined",
-                    placeholder="Paste or browse for simulation file path",
-                    messages="EAM's history output on the physics grids (pg2 grids) written by EAMv2, v3, and an intermediate version towards v4 (EAMxx).",
+                    placeholder="Paste a full path including the filename",
                 )
                 html.Label(
                     "Connectivity File",
@@ -393,13 +392,12 @@ def ui(self):
                     v_model=(self.name("data_connectivity"), ""),
                     density="compact",
                     variant="outlined",
-                    placeholder="Paste or browse for connectivity file path",
-                    messages="The horizontal grids used by EAM are cubed spheres. Since these are unstructed grids, QuickView needs to know how to map data to the globe. Therefore, for each simulation data file, a 'connectivity file' needs to be provided.",
+                    placeholder="Paste a full path including the filename",
                 )
 
             v3.VDivider()
             with v3.VCardActions(classes="pa-3"):
-                with v3.VTooltip(text="Set selected file as simulation file"):
+                with v3.VTooltip(text="Use the selected file as the simulation file"):
                     with v3.Template(v_slot_activator="{ props }"):
                         v3.VBtn(
                             v_bind="props",
@@ -412,7 +410,7 @@ def ui(self):
                             ),
                             click=self.set_data_simulation,
                         )
-                with v3.VTooltip(text="Set selected file as connectivity file"):
+                with v3.VTooltip(text="Use the selected file as the connectivity file"):
                     with v3.Template(v_slot_activator="{ props }"):
                         v3.VBtn(
                             v_bind="props",
@@ -447,7 +445,7 @@ def ui(self):
                             variant="flat",
                             click=self.cancel,
                         )
-                with v3.VTooltip(text="Import previous state file"):
+                with v3.VTooltip(text="Import the selected state file"):
                     with v3.Template(v_slot_activator="{ props }"):
                         v3.VBtn(
                             v_bind="props",