Skip to content

Conversation

softwareengineerprogrammer
Copy link
Owner

@softwareengineerprogrammer softwareengineerprogrammer commented Apr 4, 2025

Description:

User feedback has consistently indicated a need for greater transparency/visibility into what GEOPHIRES outputs are and how they are calculated. This change updates the existing Parameters Reference Outputs section to correctly display the list of existing outputs and includes internal refactoring to enable additional future enhancements to address these user requests.

  1. The schema generator now generates a geophires-result.json schema equivalent to existing schema for request (geophires-request.json)
  2. Update the Parameters Reference Outputs section to be generated from geophires-result.json schema instead of OutputParameterDicts, with the following benefits:
    1. The Outputs section now contains the list of actual outputs. The existing outputs section generated from OutputParameterDicts only loosely correlates with the fields output in the case report due to the extensive amount of transformation/display logic in Outputs.py (broadly conceptually relevant to the motivation behind Rich output code cordoning, HTML image fix NREL/GEOPHIRES-X#374), rendering it arguably useless and even actively misleading to users.
    2. Outputs are now categorized according to how they are displayed in the case report and web interface instead of a flat list
    3. The limited amount of existing output tooltip documentation is now displayed properly. This change sets the stage for follow-up work to incorporate comprehensive documentation into all input/output description/tooltip texts. This was achieved in part by adding a display_name property to OutputParameter to link instances where an output parameter was being rendered in Outputs.py with a field name different from its Name
  3. Include links to the schemas in the Parameters Reference page

Generally or partially relevant to:

  1. Include citation metadata in parameter descriptions NREL/GEOPHIRES-X#248
  2. Port theoretical basis for GEOPHIRES paper to documentation NREL/GEOPHIRES-X#331
  3. Output parameter tooltips geothermal-ui#19
  4. Defining class inputs and outputs NREL/GEOPHIRES-X#205

Testing & Verification

  1. Added unit tests for result schema generation, output parameter JSON types, and outputs RST

  2. Manually verified updated RST is correct (note this is the RST preview in PyCharm, which looks visually different from the HTML version deployed to GitHub pages): Screenshot 2025-04-04 at 13 49 45 Screenshot 2025-04-04 at 13 50 06

  3. Note that these changes do not affect any GEOPHIRES calculations, thus no example cases or other core functionality unit tests required updating


Follow-ups/TODOs:

  1. Nested dict structure should be represented according to OpenAPI standards instead of flat list of fields with categories property: 4547c3b
  2. [Follow-up/Ongoing] Continue consolidation/documentation of internal output parameters and GeophiresXResult client object/schema
  3. hip-ra-x-result.json/outputs reference update TODO
  4. Incorporate result schema tooltips into web interface: Output parameter tooltips geothermal-ui#19
  5. Deeper unit tests on generated schema content TODOs

@softwareengineerprogrammer softwareengineerprogrammer added the enhancement New feature or request label Apr 4, 2025
@softwareengineerprogrammer softwareengineerprogrammer changed the title GEOPHIRES result schema Parameters Reference Output update (GEOPHIRES result schema) Apr 4, 2025
@softwareengineerprogrammer softwareengineerprogrammer merged commit 23920bd into main Apr 4, 2025
24 checks passed
@softwareengineerprogrammer softwareengineerprogrammer deleted the geophires-result-schema-3 branch May 1, 2025 17:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant