id,node_id,number,title,user,state,locked,assignee,milestone,comments,created_at,updated_at,closed_at,author_association,active_lock_reason,draft,pull_request,body,reactions,performed_via_github_app,state_reason,repo,type
2262468762,PR_kwDOAMm_X85tqnJm,8973,Docstring and documentation improvement for the Dataset class,2005723,closed,0,,,7,2024-04-25T01:39:02Z,2024-04-30T14:40:32Z,2024-04-30T14:40:14Z,CONTRIBUTOR,,0,pydata/xarray/pulls/8973,"The example in the doc-string of the `Dataset` class prior to this commit uses an example array whose size is `2 x 2 x 3` with the first two dimensions labeled `""x""` and `""y""` and the final dimension labeled `""time""`. This was confusing due to the fact that `""x""` and `""y""` are just arbitrary names for these axes and that no reason is given for the data to be organized in a `2x2x3` array instead of a `2x2` matrix. This commit clarifies the example.

Additionally, this PR contains updates to the documentation, specifically the `user-guide/data-structures.rst` file; the updates bring the documentation examples into alignment with the doc-string change. Unfortunately, I wasn't able to build the documentation, so this will need to be checked. (I followed the instructions [here](https://docs.xarray.dev/en/stable/contributing.html#contributing-to-the-documentation), but despite `cfgrib` working fine, I got an error about how it wasn't a valid engine.)

See issue #8970 for more information.

<!-- Feel free to remove check-list items aren't relevant to your change -->

- [X] Closes #8970 ","{""url"": ""https://api.github.com/repos/pydata/xarray/issues/8973/reactions"", ""total_count"": 1, ""+1"": 0, ""-1"": 0, ""laugh"": 0, ""hooray"": 0, ""confused"": 0, ""heart"": 1, ""rocket"": 0, ""eyes"": 0}",,,13221727,pull
2261858401,I_kwDOAMm_X86G0Thh,8970,Example code in the documentation for `Dataset` is not clear,2005723,closed,0,,,13,2024-04-24T17:50:46Z,2024-04-30T14:40:15Z,2024-04-30T14:40:15Z,CONTRIBUTOR,,,,"### What is your issue?

The example code in the documentation for the `Dataset` class (e.g., [here](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)) is probably clear to those who study Earth and Atmospheric Sciences, but it makes no sense to me. Here is the code:

```python
np.random.seed(0)
temperature = 15 + 8 * np.random.randn(2, 2, 3)
precipitation = 10 * np.random.rand(2, 2, 3)
lon = [[-99.83, -99.32], [-99.79, -99.23]]
lat = [[42.25, 42.21], [42.63, 42.59]]
time = pd.date_range(""2014-09-06"", periods=3)
reference_time = pd.Timestamp(""2014-09-05"")

ds = xr.Dataset(
    data_vars=dict(
        temperature=([""x"", ""y"", ""time""], temperature),
        precipitation=([""x"", ""y"", ""time""], precipitation),
    ),
    coords=dict(
        lon=([""x"", ""y""], lon),
        lat=([""x"", ""y""], lat),
        time=time,
        reference_time=reference_time,
    ),
    attrs=dict(description=""Weather related data.""),
)
```

To be clear, I understand each individual line of code, but I don't understand why there is both a latitude/longitude and an x/y in this example or how they are supposed to be related to each other (and there do not appear to be any additional details about this dataset's intended structure). Probably due to this lack of clarity I'm having a hard time wrapping my head around what the x/y coordinates and the lat/lon coordinates are supposed to demonstrate about xarray here, or how the x/y and lat/lon values are represented in the data structure. Are the x and y coordinates in a map projection of some kind? I have worked successfully with `Dataset`s in the past, but as someone who doesn't work with geospatial data, I find myself more confused about `Dataset`s after reading this example than before.

I suspect that all that is needed is a clear description of what these data are supposed to represent, how they are intended to be used, and how x/y and lat/lon are related. If someone can explain this to me, I'd be happy to submit a PR for the docs.","{""url"": ""https://api.github.com/repos/pydata/xarray/issues/8970/reactions"", ""total_count"": 2, ""+1"": 2, ""-1"": 0, ""laugh"": 0, ""hooray"": 0, ""confused"": 0, ""heart"": 0, ""rocket"": 0, ""eyes"": 0}",,completed,13221727,issue