Enhance GenVxMask wrapper to compute time-varying masks using Local Solar Time

[jvigh]

Describe the New Feature

The goal of this use case is to enhance the gen_vx_mask tool to compute time-varying masks using Local Solar Time (LST).

Background: SWPC would like to be able to stratify verification results by Local Solar Time (e.g., local time, instead of UTC). Solar time is similar to azimuthal solar angle (which relates to the position of the sun), but is expressed in time rather than angle. The exact calculation of LST can be quite complex and involve computing the solar subpoint. However, the following approximate formula is usually accurate enough (+/- a few seconds or minutes) in the low and mid-latitudes.

LST_approximate = Time_UTC + Longitude_degrees/15

When the sun is at its highest point of the day, LST = 12:00 (Local Solar Noon)

Currently, there does not seem to be a way to compute and use LST in MET or the METplus analysis suite. Ideally, in the future MET and the METplus analysis suite will be modified to directly support handling LST as an auxiliary time variable, but this would require adding an extra column to all of the tools and downstream processing infrastructure. It is beyond the scope of the current issue, but should be on the radar in the strategic development roadmap.

As a workaround, this issue will involve modifying the gen_vx_mask tool to compute time-varying masks using LST.

The gen_vx_mask tool already supports solar altitude (solar_alt) and solar azimuth (solar_azi) masking by computing the solar altitude and azimuth values at each grid point for the time defined by the mask_file setting. mask_file may either be set to an explicit time string in YYYYMMDD[_HH[MMSS]] format or to a gridded data file. If set to a gridded data file, the -mask_field command line option specifies the field of data whose valid time should be used. If the -thresh command line option is not used, the raw solar altitude or azimuth value for each grid point will be written to the output. If it is used, the resulting binary mask field will be written. This option is useful when defining a day/night mask.

This issue will enhance gen_vx_mask to support a new option "-type solar_time" and provide a way to define the beginning/ending solar time to be included in the mask.

Acceptance Testing

Data are described in SWPC-RT #55
Describe tests required for new functionality.

Time Estimate

Estimate the amount of work required here.
Issues should represent approximately 1 to 3 days of work.

Sub-Issues

Consider breaking the new feature down into sub-issues.

• Add a checkbox for each sub-issue here.

Relevant Deadlines

All work on this issue must be completed by 09/30/24 if using the account key below.

Funding Source

2784543 (NOAA SWPC/OSTI)

Define the Metadata

Assignee

• Select engineer(s) or no engineer required
• Select scientist(s) or no scientist required

Labels

• Select component(s)
• Select priority
• Select requestor(s)

Projects and Milestone

• Select Repository and/or Organization level Project(s) or add alert: NEED CYCLE ASSIGNMENT label
• Select Milestone as the next official version or Future Versions

Define Related Issue(s)

Consider the impact to the other METplus components.

• METplus, MET, METdataio, METviewer, METexpress, METcalcpy, METplotpy
• Enhance gen_vx_mask to support a new local solar time masking region option MET#2966

New Feature Checklist

See the METplus Workflow for details.

• Complete the issue definition above, including the Time Estimate and Funding source.
• Fork this repository or create a branch of develop.
  Branch name: feature_<Issue Number>_<Description>
• Complete the development and test your changes.
• Add/update log messages for easier debugging.
• Add/update unit tests.
• Add/update documentation.
• Add any new Python packages to the METplus Components Python Requirements table.
• Push local changes to GitHub.
• Submit a pull request to merge into develop.
  Pull request: feature <Issue Number> <Description>
• Define the pull request metadata, as permissions allow.
  Select: Reviewer(s) and Development issues
  Select: Repository level development cycle Project for the next official release
  Select: Milestone as the next official version
• Iterate until the reviewer(s) accept and merge your changes.
• Delete your fork or branch.
• Close this issue.

[JohnHalleyGotway]

Need additional discussion to figure out how to address these needs in METplus.
Recommend that @jvigh schedule a meeting to brainstorm.

[JohnHalleyGotway]

Note that I have removed @JohnHalleyGotway and @bikegeek as assignees on this METplus wrapper update issue. I added @georgemccabe since he is best-suited to update the GenVxMask wrapper. I'll create a separate issue to enhance the MET gen_vx_mask tool to actually do this.