Add get_warming_level_from_period, rename old function

[RondeauG]

Pull Request Checklist:

• This PR addresses an already opened issue (for bug fixes / features)
  • This PR fixes #xyz
• (If applicable) Documentation has been added / updated (for bug fixes / features).
• (If applicable) Tests have been added.
• This PR does not seem to break the templates.
• CHANGELOG.rst has been updated (with summary of main changes).
  • Link to issue (:issue:number) and pull request (:pull:number) has been added.

What kind of change does this PR introduce?

• Adds xs.get_warming_level_from_period to find the warming level associated to a given period.

Does this PR introduce a breaking change?

• For clarity, I changed get_warming_level to get_period_from_warming_level.

Other information:

• This function is needed if we want to easily implement @coxipi's modified warming levels.

[aulemahal]

We'll also eventually need a column in our global_tas file with the observed temperatures.

Don't we already have 6 such sources ?

>>> ds.where(ds.experiment == 'obs', drop=True).source
<xarray.DataArray 'source' (simulation: 6)> Size: 384B
array(['Berkeley-Raw', 'Berkeley', 'GISTEMPv4', 'HadCRUT5',
       'NOAAGlobalTempv5', 'JRA-55'], dtype='<U16')
Coordinates:
    mip_era      (simulation) <U5 120B 'obs' 'obs' 'obs' 'obs' 'obs' 'obs'
    source       (simulation) <U16 384B 'Berkeley-Raw' 'Berkeley' ... 'JRA-55'
    experiment   (simulation) <U6 144B 'obs' 'obs' 'obs' 'obs' 'obs' 'obs'
    member       (simulation) <U10 240B '' '' '' '' '' ''
    data_source  (simulation) <U33 792B 'Computed following WMO guidelines' ....
Dimensions without coordinates: simulation

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[RondeauG]

Do we want get_horizon_from_warming_level instead of period, to match the return_horizon argument?

[juliettelavoie]

Do we want get_horizon_from_warming_level instead of period, to match the return_horizon argument?

Horizon is a more precise word than the general period, as it refers specifically to if we are showing data by temporal horizon or warming level. I like it. But then, I would also have get_warming_level_from_horizon to keep the symmetry.

[RondeauG]

Do we want get_horizon_from_warming_level instead of period, to match the return_horizon argument?

Horizon is a more precise word than the general period, as it refers specifically to if we are showing data by temporal horizon or warming level. I like it. But then, I would also have get_warming_level_from_horizon to keep the symmetry.

Done. To be fully consistent, I rename return_horizon with return_period, since this is closer to what it does.

[aulemahal]

@lpcaron has a strong opinion against horizon and I'm beginning to catch on. I think "period" is more adequate for the use we make of it. Horizon as a notion of "limit" that doesn't apply.

[juliettelavoie]

@lpcaron has a strong opinion against horizon and I'm beginning to catch on. I think "period" is more adequate for the use we make of it. Horizon as a notion of "limit" that doesn't apply.

not sure I get the notion of "limit" with horizon...

Note that the IPCC atlas uses "periods" to choose between time horizon/period and GWL

[RondeauG]

We use horizon in multiple places throughout xscen, including as a dimension/coordinate and as arguments. Does that mean that we should change all of those to period?

[juliettelavoie]

The Copernicus Interactive Climate Atlas also uses the word "term", near term, medium term and long term. get_term_from_warming_level ?

[aulemahal]

We use it in xscen because Ouranos uses it everywhere...

Sorry to raise this somewhat unrelated issue on this PR. We could also merge this with whatever solution and discuss the rest in a larger group.

But, the "limit" I'm mentioning comes from the first meaning of "horizon". When used temporally, I hear it as a blurry timeframe set in the future in a way a bit slightly precise than "term". I feel that the canadians translators agree with me : https://www.btb.termiumplus.gc.ca/tpv2alpha/alpha-eng.html?lang=eng&i=1&srchtxt=Horizon&index=alt&codom2nd_wet=1#resultrecs

Like, a common construction like "Horizon 2050" means a deadline set in 2050. In climate terms, we usually assume that it means that 2050 is in the middle (ish) of the period from which we want statistics, but that's not what the term means, rather it is our scientific analysis of what data is needed.

[juliettelavoie]

I looked again at how we use horizon. I think we can keep horizon in xscen but with a more specific definition.

• Use period(s) we are cutting time to a given period but we keep the frequency (usually day). The format is ['XXXX','XXXX'].
• Use horizon, we have a single value for that horizon (usually a climatological mean) with a horizon coord that has the format "XXXX-XXXX" (or even "+XdegC"). Like the output of xs.produce_horizon.

With this logic, we would have get_period_from_warming_level because the output is a list and the climatological mean has not been done yet.

[RondeauG]

Right, so this is my suggestion:

• get_warming_level --> get_period_from_warming_level(realization, wl, window, ..., return_period)
• New function get_warming_level_from_period(realization, period).

[juliettelavoie]

@aulemahal OK I understand what you mean now.

I still think we need a distinction in xscen between the two cases in my last comments.

And I think Ouranos needs to clearly define the vocabulary for explaining the framework used to show results: GWL or time [enter consensus word here].

[juliettelavoie]

Right, so this is my suggestion:

* `get_warming_level` --> `get_period_from_warming_level(realization, wl, window, ..., return_period)`

* New function `get_warming_level_from_period(realization, period)`.

could you flip return_period to return_year? Defautl would be to return a period ['XXXX','XXXX'] (as the name of the function suggests) and return_year would give you the option to get the middle year XXXX.

EDIT: as return_period is already a thing in frequency analysis

[lpcaron]

And I think Ouranos needs to clearly define the vocabulary for explaining the framework used to show results: GWL or time [enter consensus word here].

Agreed. I'm working hard to remove the mentions and the use of the word horizon, but there is a lot of inertia in the system...

[juliettelavoie]

merci Gab!