Reduce confusion about fsurdat vars LANDFRAC_PFT, PFTDATA_MASK vs. history vars landfrac, landmask, pftmask

[slevis-lmwg]

@lawrencepj1 brought up that

• fsurdat vars LANDFRAC_PFT and PFTDATA_MASK include more total land on the planet than supported by high res satellite data, much of it in SE Asia/Indonesia
• fsurdat files do not contain an accurate land mask for use in data processing
• domain files (now obsolete) contain more accurate land mask data.

fsurdat files intentionally omit land mask info (other than the pft-related vars already mentioned) in order to make fsurdat files flexible for use with any land mask provided as the inverse of an ocean mask (supplied in /ccs_config/component_grids_nuopc.xml).

In a meeting on 4/12/2022 with @lawrencepj1 @ekluzek @mvertens @slevisconsulting we proposed the following steps toward reducing this confusion:

• Eliminate fsurdat variable LANDFRAC_PFT because it is not used and because it overestimates land area relative to high res satellite data.
• Add a warning to fsurdat variable PFTDATA_MASK stating that it intentionally overestimates land area relative to high res satellite data and should not be used in data processing. This overestimation ensures that we do not miss PFT data in grid cells with tiny fractions of land. CTSM users should use history fields landfrac and landmask for a representation of grid cells used as land vs. ocean in their simulations. Moreover, users should use their own landfrac/landmask data if they find that the model's landfrac/landmask variables disagree with high res satellite data.

@ekluzek determined that fsurdat variable PFTDATA_MASK is currently required in fsurdat files, but only so that it may be written to history files as pftmask. So @ekluzek suggests that we stop writing pftmask to history and possibly remove PFTDATA_MASK from fsurdat, as well. Can anyone think of reasons that we may regret such a choice later?

Update from Bill Sacks (2022-09-08): What we want to do is:

• On the surface datasets, add metadata to LANDFRAC_PFT making it clear that this is NOT the same as landfrac in the simulation
• Possibly remove PFTDATA_MASK from the surface datasets if it is simply a 0/1 version of LANDFRAC_PFT
• Do NOT output pftmask on the history files

[slevis-lmwg]

CC: @billsacks @dlawrenncar @wwieder based on the group included in the corresponding email earlier today.

[slevis-lmwg]

Summing up the options presented here:

1. Simplest option is to eliminate fsurdat variables LANDFRAC_PFT and PFTDATA_MASK in New parallel surface dataset generation with online regridding #1663
   and before then to remove pftmask from history.
2. Same but keep fsurdat variable PFTDATA_MASK with a warning attached to its metadata.

[slevis-lmwg]

I confirmed the second tickbox, i.e.
"Possibly remove PFTDATA_MASK from the surface datasets if it is simply a 0/1 version of LANDFRAC_PFT"
by doing the following in matlab:

landfrac_pft(landfrac_pft > 1) = 1;
mask_from_frac = ceil(landfrac_pft);
mask_diff = mask_from_frac - double(pftdata_mask);

Notes:

• Line 1 ensures that landfrac_pft doesn't exceed 1 (initially it did).
• Line 2 determines the mask from landfrac_pft by setting values greater than zero to 1.
• Line 3 results in mask_diff = 0 everywhere.

[billsacks]

@slevisconsulting @lawrencepj1 - following up from discussion at today's ctsm software standup: I see that LANDFRAC_PFT is still on the surface datasets. For my changes to treat % areas more rigorously on the coasts, I am planning to ingest the actual landfrac from the PFT dataset (rather than just the mask). Along with this, I propose using this actual landfrac rather than mask for the LANDFRAC_PFT on the surface dataset. Let me know if you have any objection to this.

[slevis-lmwg]

I am fine with this suggestion, and I would not mind reviewing the corresponding code when it's ready. Thank you, @billsacks .