Rename ICON facet var_type -> output_stream

[schlunma]

Description

Today I learned that the facet var_type that we use for ICON data is actually called output_stream by the ICON modeling community.

To use a consistent nomenclature here, I suggest renaming var_type -> output_stream in our code and documentation. This makes it also easier for new users from the ICON modeling community.

Considerations about backwards-compatibility

var_type is only used for data finding, which is configured in the ICON data source configuration in data-native-icon.yml. This configuration file is not loaded by default, so there's no way we can force users to update their ICON data source configuration.

In addition, there are no published ICON recipes; all of them are custom user recipes (again, we cannot force users to update those). However, I expect that most of these recipe do not have var_type facet, because those are added automatically by ESMValCore using the ICON extra facets. The latter is the only thing that is changes in this PR apart from documentation.

Considering all of the above, we need to consider the following cases when thinking about backwards-compatibility:

var_type in user's recipe	var_type in user's extra facets	var_type in user's configuration	How to handle backwards compatibility?
no	no	no	trivial
yes	no	no	trivial: var_type is simply ignored
no	yes	no	trivial: var_type is simply ignored
yes	yes	no	trivial: var_type is simply ignored
no	no	yes	not trivial: see below
yes	no	yes	trivial: var_type from recipe is used)
no	yes	yes	trivial: var_type from extra facets is used)
yes	yes	yes	trivial: var_type from recipe and extra facets is used)

The only non-trivial (but most likely) case is if the configuration file requires a var_type, but this is not given via the recipe or user's extra facets. In the past, the default extra facets have supplied this, but now they only supply output_stream. As far as I can tell, the easiest solution to ensure backwards-compatibility is to expand LocalDataSource so that the missing var_type facet is read from output_stream.

Advantages:

• A deprecation warning is only raised if absolutely necessary (e.g., if users want to continue using var_type in their configuration by explicitly specifying it in their recipes/extra facets, they can just do that; no warning is raised)
• No superfluous var_type needs to be added to the dataset facets
• This works for the recipe and Python API interfaces

Disadvantages:

• LocalDataSource will contain special project-specific code for some time.

Deprecations (since v2.16.0, will be removed in v2.18.0) #

Usage of extra facet var_type for ICON: please use output_stream instead.

Link to documentation:

• https://esmvaltool--3212.org.readthedocs.build/projects/ESMValCore/en/3212/develop/fixing_data.html#locate-data
• https://esmvaltool--3212.org.readthedocs.build/projects/ESMValCore/en/3212/quickstart/find_data.html#icon

---

Checklist

It is the responsibility of the author to make sure the pull request is ready to review. The icons indicate whether the item will be subject to the 🛠 Technical or 🧪 Scientific review.

• 🧪 The new functionality is relevant and scientifically sound
• 🛠 This pull request has a descriptive title and labels
• 🛠 Code is written according to the code quality guidelines
• 🧪 and 🛠 Documentation is available
• 🛠 Unit tests have been added
• 🛠 Changes are backward compatible
• 🛠 Any changed dependencies have been added or removed correctly
• 🛠 The list of authors is up to date
• 🛠 All checks below this pull request were successful

---

To help with the number pull requests:

• 🙏 We kindly ask you to review two other open pull requests in this repository

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.46%. Comparing base (9754bd4) to head (f74b396).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3212      +/-   ##
==========================================
- Coverage   96.46%   96.46%   -0.01%     
==========================================
  Files         281      281              
  Lines       16320    16331      +11     
==========================================
+ Hits        15743    15753      +10     
- Misses        577      578       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[hb326]

Thanks for this, @schlunma!
I think it is good to be consistent with the rest of the ICON community in our naming, so I am in favor of this change.