carray-netcdf 1.0.13 → 2.0.0

data/docs/04_codec.md

@@ -0,0 +1,373 @@
+# Codecs and CF conventions
+
+A **codec** turns raw on-disk values into Ruby-side values on read and back again on write. There are three built in:
+
+- **`Identity`** — no transform. Raw values in, raw values out.
+- **`CF`** — the CF Conventions value transforms.
+- **`COARDS`** — CF's predecessor; functionally identical for the value transforms this codec touches.
+
+The codec runs transparently inside `Var#[]` / `Var#[]=` (both array and scalar paths — see the [reading chapter](02_reading.md#hyperslab-reads-ncvari-j-k)). You usually don't call codec methods directly.
+
+## What CF actually does (and doesn't)
+
+| CF attribute | Codec does |
+|---|---|
+| `_Unsigned` | Read: bit-reinterpret signed on-disk type to its unsigned counterpart (`int8 → uint8`, etc.).  Write: reverse.  Runs FIRST so fill/valid/scale all see the correct numeric interpretation. |
+| `_FillValue`, `missing_value` | Read: mask (`UNDEF`).  Write: `UNDEF` → fill sentinel.  If `_Unsigned` is set, the attribute value is reinterpreted to unsigned space before comparison. |
+| `scale_factor`, `add_offset` | Read: `packed × scale + offset`.  Write: `round((v − offset) / scale)` into var type. |
+| `valid_range`, `valid_min`, `valid_max` | Read (opt-in): out-of-range → `UNDEF`.  Write: no effect. |
+| `units` = `"<u> since <ref>"` (+ `calendar`) | Read: `CATime`.  Write: `CATime` → count since ref (a fraction only into a float variable). |
+| `units` = anything else (`"m s-1"`, `"K"`, `"kg m-3"`, …) | Raw attribute, **no UDUNITS conversion**. |
+| everything else (`standard_name`, `grid_mapping`, `cell_methods`, `coordinates`, `ancillary_variables`, …) | Raw attribute, no interpretation. |
+
+The last two rows are important: **this codec is a var-local value codec, not a CF data model builder**.  Coordinate systems, cell methods, standard names, grid mappings — all preserved as attributes (`var.att("grid_mapping")` works), but the codec does not interpret them, nor does it walk to sibling variables.  If you need CF data model support (a real coordinate-system layer akin to netCDF-Java's `CoordSystemBuilder`), either build it on top of this codec or reach for a heavier library.
+
+### Contract for codec methods
+
+Every codec method takes `(var, ca)` and only that.  A codec:
+
+- Reads attributes off `var` (own attributes only).
+- Transforms the CArray `ca` (own values only).
+- **Does NOT** walk to `var.file` to reach other variables or global state. Ruby cannot enforce this structurally, but doing so is a contract violation and puts the codec on the wrong side of the boundary.
+- **Does NOT** rely on `var.dims` beyond reading their names (for documentation purposes, if at all) — again, that leaves the variable's frame of reference.
+
+The dispatch that picks a codec at File.open time DOES look at the whole file (specifically the `Conventions` attribute) — that's a one-shot selection, not a per-transform operation, so it stays on the right side of the boundary.
+
+## Codec selection
+
+By default, `File.open` inspects the `Conventions` global attribute:
+
+```ruby
+NC::File.open("cf_file.nc") do |nc|
+  nc.codec         # => #<CA::NetCDF::Codec::CF ...>
+end
+
+NC::File.open("coards_file.nc") do |nc|
+  nc.codec         # => #<CA::NetCDF::Codec::COARDS ...>
+end
+
+NC::File.open("no_conventions.nc") do |nc|
+  nc.codec         # => CA::NetCDF::Codec::Identity   (raw values)
+end
+```
+
+Naming rules (checked in registry order):
+
+- `Conventions: "COARDS"` (or combos like `"COARDS/CF-1.0"`) → `COARDS`.
+- `Conventions: "CF-1.7"` / `"CF-1.8"` / `"CF 1.7"` / `"CF"` → `CF`.
+- When the whole string matches neither, each of its tokens (split on spaces, commas and slashes) is tried, so `"ACDD-1.3, CF-1.8"` → `CF`.
+- Anything else, including missing → `Identity`.
+
+Override on open:
+
+```ruby
+NC::File.open("data.nc", codec: :identity)                        # raw only
+NC::File.open("data.nc", codec: :cf)                              # force CF
+NC::File.open("data.nc", codec: :coards)                          # force COARDS
+NC::File.open("data.nc", codec: [:cf, mask_valid_range: true])    # CF with option
+NC::File.open("data.nc", codec: NC::Codec::CF.new(mask_valid_range: true))
+NC::File.open("data.nc", codec: NC::Codec::CF)                    # a class: instantiated with defaults
+```
+
+## `_FillValue` and `missing_value`
+
+Round-trip:
+
+```ruby
+NC::File.create("fill.nc") do |nc|
+  nc.def_dim("n", 5)
+  nc.def_var("v", :short, ["n"], _FillValue: -32768)
+  nc.def_att("Conventions", "CF-1.7")
+  nc["v"] = CA_SHORT([10, -32768, 30, 40, 50])   # cell 1 written as fill
+end
+
+NC::File.open("fill.nc") do |nc|
+  v = nc["v"].to_ca
+  v.is_masked[1]      # => true    (decoded to mask)
+  v[1]                # => UNDEF   (scalar decode too)
+  v.count_masked      # => 1
+end
+
+# Write UNDEF -> fill on encode
+NC::File.open("fill.nc", :write) do |nc|
+  nc["v"][3] = UNDEF   # written back as -32768
+end
+```
+
+If a variable has **both** `_FillValue` and `missing_value`, both sentinels are masked. `missing_value` may be a scalar or an array (multiple sentinels).
+
+Writing `UNDEF` to a variable without a `_FillValue` raises:
+
+```ruby
+ca = CA_SHORT([1, 2, 3])
+ca[1] = UNDEF
+nc["v"] = ca   # ArgumentError: no _FillValue to encode masked cells
+```
+
+## `scale_factor` and `add_offset`
+
+CF's packing formula (§8.1):
+
+```
+unpacked = packed × scale_factor + add_offset
+packed   = round((unpacked − add_offset) / scale_factor)
+```
+
+Round-trip:
+
+```ruby
+NC::File.create("packed.nc") do |nc|
+  nc.def_dim("n", 4)
+  nc.def_var("temp_kelvin", :short, ["n"],
+             scale_factor: 0.01, add_offset: 273.15, units: "K")
+  nc.def_att("Conventions", "CF-1.7")
+
+  # write physical values; codec packs them into short
+  nc["temp_kelvin"] = CA_DOUBLE([273.15, 283.15, 293.15, 303.15])
+end
+
+NC::File.open("packed.nc") do |nc|
+  nc["temp_kelvin"].to_ca.to_a   # => [273.15, 283.15, 293.15, 303.15]
+end
+
+NC::File.open("packed.nc", codec: :identity) do |nc|
+  nc["temp_kelvin"].to_ca.to_a   # => [0, 1000, 2000, 3000]  (raw packed short)
+end
+```
+
+**Rounding is required.** A bare cast to an integer variable would truncate (`1.0 / 0.1 == 9.999...` → `9`); the codec rounds. Symmetric on read: no rounding, just the linear transform.
+
+Interaction with `_FillValue`: **fill is judged in packed space, before unpacking.** So `_FillValue: -32768` on a packed short is compared against the raw short values, not against the unpacked physical values.
+
+## `valid_range` / `valid_min` / `valid_max`
+
+CF says values outside `valid_range` are missing. The codec **does not** apply this by default — see the design note in `codec.rb` — because producers often set conservative ranges and silently masking a large fraction of the data is a debugging trap. `_FillValue` masking (which is per-cell explicit) is on; range masking (which is per-file policy) is opt-in.
+
+```ruby
+# default: raw attribute readable, values not masked
+NC::File.open("ranged.nc") do |nc|
+  nc["v"].att("valid_range")   # => e.g. [0, 100]
+  nc["v"].to_ca                # => everything decoded, out-of-range visible
+end
+
+# opt-in: hard-mask
+NC::File.open("ranged.nc", codec: [:cf, mask_valid_range: true]) do |nc|
+  nc["v"].to_ca                # => values outside [0, 100] are UNDEF
+end
+```
+
+Rules (CF §2.5.1):
+- `valid_range` takes precedence over `valid_min`/`valid_max`.
+- All three are judged in **packed** space (before scale/offset). Encode a physical-range test yourself if you want the physical-space check.
+- Attribute type should match the variable's on-disk type; the codec passes whatever's on disk through to the comparison.
+
+## CF time coordinates
+
+CF encodes time as a numeric count with a units string:
+
+```
+units: "hours since 2022-01-01T00:00:00Z"
+units: "days since 2000-01-01"
+units: "seconds since 1970-01-01 00:00:00"
+units: "5 days since 2024-06-15"          # any positive integer count
+```
+
+The codec maps this to CATime on read and back on write.
+
+### Read: `count × base since ref` → `CATime`
+
+```ruby
+NC::File.open("cf_time.nc") do |nc|
+  t = nc["time"].to_ca
+  t.class                # => CATime
+  t.unit                 # => #<CATime::Resolution 1 h>
+  t[0]                   # => #<CATime::Element 2022-01-01T00:00:00Z>
+  t[0].to_time           # => 2022-01-01 00:00:00 UTC (Ruby Time)
+  t[0].to_date           # => #<Date: 2022-01-01>
+end
+```
+
+### Write: `CATime` → `count since ref`
+
+```ruby
+NC::File.create("t.nc") do |nc|
+  nc.def_dim("time", 24)
+  nc.def_var("time", :int, ["time"],
+             units: "hours since 2022-01-01T00:00:00Z", calendar: "standard")
+  nc.def_att("Conventions", "CF-1.7")
+
+  nc["time"] = CArray.time_series("2022-01-01T00:00:00Z", count: 24, unit: :h)
+end
+```
+
+Scalar assignment works too:
+
+```ruby
+NC::File.open("t.nc", :write) do |nc|
+  # a CATime::Element
+  nc["time"][0] = CArray.time("2022-01-01T05:00:00Z", unit: :h)[0]
+  # or a plain integer (interpreted as "count since ref" — bypasses CATime encode)
+  nc["time"][1] = 10
+end
+```
+
+### N-of-a-unit intervals: `"5 days since ..."`
+
+The codec stores CATime at the base resolution (day, in this case) and folds the count `5` into the numeric values. That way any reference date representable in the base works — including the normal case where the ref doesn't land on the coarser `count × base` grid from the epoch (e.g. `"5 days since 2024-06-15"` — 2024-06-15 is not on a 5-day-from-1970 grid, but it IS on the day grid). The count information isn't lost: it stays on `atts["units"]`, we just don't bake it into CATime's storage tick.
+
+```ruby
+# raw N reads as N*5 days past 2024-06-15
+dt = CA_INT64([0, 5, 10]).time(unit: :D, origin: "2024-06-15")
+# writing dt to units="5 days since 2024-06-15":
+#   codec.timesteps(unit: :D, origin: "2024-06-15") -> [0, 5, 10]
+#   then / 5 -> [0, 1, 2]  (on-disk)
+```
+
+### Float time coordinates
+
+Many CF files store time as `double`. Whole values decode at the declared base; a value with a fraction is carried to the first finer unit that holds it whole, so nothing is rounded away:
+
+```
+units: "hours since ..." with float values 0.0, 1.0, 2.0  -> CATime at 1 h
+units: "days since ..."  with float values 0.0, 0.5, 1.25 -> CATime at 1 h: +0 h, +12 h, +30 h
+```
+
+Only `year` and `month` fractions are rounded to the nearest whole tick, since those units have no fixed length.
+
+On write, an instant finer than the units' interval is written as a fraction into a float variable (`01:30` into `"days since ..."` is `0.0625`). An integer variable can't hold one, so the write raises `ArgumentError` instead of truncating.
+
+### Calendars
+
+The codec handles these calendar attribute values:
+
+- `standard`, `gregorian`, `proleptic_gregorian`, or missing → CATime (proleptic Gregorian, UTC).
+- Anything else — `noleap`, `365_day`, `all_leap`, `366_day`, `360_day`, `julian`, `none` — is unsupported. The codec warns once per distinct calendar value and returns raw values unchanged. Writing a `CATime` to a variable with an unsupported calendar raises.
+
+For post-1582 dates, `standard` and `proleptic_gregorian` agree, so CATime is exact for modern climate/ocean data. Pre-1582 or non-standard calendars belong in an external gem.
+
+## Identity codec
+
+Skip all transforms — raw bytes only:
+
+```ruby
+NC::File.open("data.nc", codec: :identity) do |nc|
+  nc["temp"].to_ca                 # packed shorts, or whatever's on disk
+  nc["time"].to_ca                 # raw int/double, no CATime wrapping
+  nc["temp"][0, 0, 0]              # raw scalar, no _FillValue -> UNDEF
+end
+```
+
+Useful for round-tripping unknown files, debugging what a producer actually wrote, or side-stepping a codec bug.
+
+## COARDS codec
+
+COARDS (1995) is CF's predecessor. Every adherent COARDS file is also an adherent CF file — spec-inclusion, not just similarity — so `COARDS < CF` inherits every transform; only `self.claims?` differs. Everything above (`_FillValue`, scale/offset, `valid_range`, CF time, calendar policy) applies verbatim.
+
+```ruby
+NC::File.open("coards_file.nc") do |nc|
+  nc.codec.is_a?(NC::Codec::COARDS)   # => true
+  nc.codec.is_a?(NC::Codec::CF)       # => true (COARDS < CF)
+  # all the same transforms work
+end
+```
+
+**Check `is_a?(COARDS)` BEFORE `is_a?(CF)`** in an upper-layer dispatcher — COARDS pins the coordinate axis order to `T, Z, Y, X`, so an upper layer that treats a COARDS file as generic CF may silently accept looser axis orderings.  (This value codec doesn't touch axis order, so at THIS layer the distinction doesn't matter; it matters at the layer above.)
+
+`Conventions` strings that route to COARDS:
+- `"COARDS"` alone.
+- Combos starting with `COARDS` (e.g. `"COARDS/CF-1.0"`) — some tools emit these.
+
+COARDS predates the `calendar` attribute; a COARDS time variable without an explicit calendar lands on the same proleptic-Gregorian axis as CF `"standard"` (identical for post-1582 dates).
+
+## Writing your own codec
+
+The codec interface is minimal:
+
+```ruby
+class MyCodec
+  # Optional: class method for auto-selection by the Conventions attribute.
+  # Only inspects the Conventions string — deliberately does NOT take the
+  # File, to keep dispatch out of the CDM Layer 2 territory (a "look at
+  # coordinate variables to sniff CF" hook is intentionally not provided).
+  def self.claims?(conventions_string)  = ...
+
+  # Required: the two transforms.  Both are var-local — see the contract
+  # note earlier in this chapter.
+  def decode(var, ca) = ...     # var: Var, ca: raw CArray -> processed value
+  def encode(var, ca) = ...     # var: Var, ca: value -> raw CArray for the on-disk write
+end
+
+CA::NetCDF::Codec.register(MyCodec)
+```
+
+Registered codecs are matched in reverse registration order (later registrations win).  `resolve` accepts:
+
+- `:auto` (default) — match by `Conventions`; fallback `Identity`
+- `:identity` / `false` / `nil` → `Identity`
+- `:cf`, `:coards` → the named codec with defaults
+- `[:cf, opts]`, `[:coards, opts]` → with keyword options
+- a `Module` (used as-is, e.g. `Identity`)
+- any object that responds to `#decode(var, ca)` and `#encode(var, ca)`
+
+So an ad-hoc codec doesn't even need to register — you can pass an instance directly:
+
+```ruby
+class OnlyMasksCodec
+  def decode(var, ca)
+    # apply only fill masking, skip everything else
+    fill = var.att("_FillValue") or return ca
+    out = ca.copy
+    out[:eq, fill] = UNDEF
+    out
+  end
+  def encode(var, ca) = ca   # writes unchanged
+end
+
+NC::File.open("data.nc", codec: OnlyMasksCodec.new) do |nc|
+  ...
+end
+```
+
+## Full pipeline order
+
+Decode (read):
+
+1. `decode_unsigned` — `_Unsigned` reinterprets signed on-disk bits to their unsigned counterpart.  Runs FIRST so every subsequent comparison (fill, valid_range) sees the numerically-correct value.
+2. `decode_fill` — `_FillValue` / `missing_value` → mask (in unsigned space if `_Unsigned` was set; the attribute value is reinterpreted).
+3. `decode_valid` — `valid_range` / `valid_min` / `valid_max` → mask (opt-in, same space as fill).
+4. `decode_scale` — `packed × scale + offset`.
+5. `decode_time` — `count-since-ref` → `CATime`.
+
+Encode (write) runs in reverse:
+
+1. `encode_time` — `CATime` → `count-since-ref`.
+2. `encode_scale` — `round((v − offset) / scale)` for integer var types.
+3. `encode_fill` — `UNDEF` → fill sentinel (in the user's unsigned space).
+4. `encode_unsigned` — reinterpret unsigned user values back to signed on-disk bits.
+
+(`valid_range` has no defined encode direction in CF, and the codec doesn't invent one.)
+
+## Debug / inspect a variable's decode
+
+```ruby
+NC::File.open("data.nc") do |nc|
+  v = nc["temp"]
+  v.atts                       # everything the codec might read
+  v.codec                      # which codec will run
+
+  raw     = v.raw              # bypass codec → the on-disk values
+  decoded = v.to_ca            # === v.codec.decode(v, v.raw)   (identity)
+
+  # diff them cell by cell to see what the codec actually changed
+end
+```
+
+The identity `v.to_ca == v.codec.decode(v, v.raw)` holds by construction, so `v.raw` is the canonical descent point when you want to work below the codec — no `instance_variable_get` needed.
+
+You can also open the file with `codec: :identity` to skip decoding for every read in the block:
+
+```ruby
+NC::File.open("data.nc", codec: :identity) do |nc|
+  nc["temp"].to_ca            # raw bytes, uniformly for every variable
+end
+```

data/docs/05_groups.md

@@ -0,0 +1,200 @@
+# Groups (NetCDF-4)
+
+NetCDF-4 files can organize their contents in a tree of **groups** — much like directories in a filesystem. Each group has its own dimensions, variables, and global attributes; nested groups form a hierarchy.
+
+The classic NetCDF-3 model is a single root group; every file has one, so in this library **every `File` IS a Group** (the root group). Everything you can do on `File` — `def_dim`, `def_var`, `def_att`, `nc[name]`, `nc[name] = ...` — is a `Group` method, plus subgroup navigation.
+
+## Creating groups
+
+Groups only work in NetCDF-4 format, so pass `netcdf4: true`:
+
+```ruby
+require "carray-netcdf"
+NC = CA::NetCDF
+
+NC::File.create("model.nc", netcdf4: true) do |nc|
+  nc.def_dim("time", 12)
+
+  ocean = nc.def_group("ocean")
+  ocean.def_dim("depth", 50)
+  ocean.def_var("temperature", :float, ["time", "depth"])   # 'time' inherited from root
+
+  atm = nc.def_group("atmosphere")
+  atm.def_dim("altitude", 30)
+  atm.def_var("pressure", :float, ["time", "altitude"])
+
+  # Nested subgroups
+  surface = ocean.def_group("surface")
+  surface.def_var("sst", :float, ["time"])
+end
+```
+
+`def_group` returns the new `Group` and stores it under `parent.groups[name]`.
+
+## Navigating groups
+
+```ruby
+NC::File.open("model.nc") do |nc|
+  nc.groups                    # => {"ocean" => Group, "atmosphere" => Group}
+  nc.group("ocean")            # => Group
+  nc.group?("ocean")           # => true
+
+  ocean = nc.group("ocean")
+  ocean.name                   # => "ocean"
+  ocean.path                   # => "/ocean"
+  ocean.parent                 # => the File (root Group)
+  ocean.root?                  # => false
+
+  surface = ocean.group("surface")
+  surface.path                 # => "/ocean/surface"
+
+  nc.name                      # => "/"    (netcdf's root name)
+  nc.path                      # => "/"
+  nc.root?                     # => true
+end
+```
+
+## Accessing variables in groups
+
+Three equivalent forms:
+
+```ruby
+NC::File.open("model.nc") do |nc|
+  # (1) navigate then subscript
+  temp = nc.group("ocean")["temperature"]
+
+  # (2) relative path
+  temp = nc["ocean/temperature"]
+
+  # (3) absolute path
+  temp = nc["/ocean/temperature"]
+
+  # All three are the same Var object.
+end
+```
+
+Full-path lookup works on any `Group` as the receiver:
+
+```ruby
+ocean = nc.group("ocean")
+ocean["surface/sst"]      # relative to ocean       -> Var
+ocean["/ocean/temperature"]  # absolute from root   -> Var
+```
+
+## Writing to a variable in a group
+
+Same pattern:
+
+```ruby
+NC::File.open("model.nc", :write) do |nc|
+  # via group
+  nc.group("ocean")["temperature"] = big_array
+
+  # via path
+  nc["/ocean/temperature", 0, nil] = one_slice
+  nc["/ocean/temperature", 0, 0]   = 273.15   # single point
+end
+```
+
+## Dimension inheritance
+
+NetCDF-4 lets a variable in a subgroup reference a dimension defined in any ancestor group. `def_var` resolves dimension names by walking up the tree:
+
+```ruby
+NC::File.create("nested.nc", netcdf4: true) do |nc|
+  nc.def_dim("time", 24)             # defined at root
+  child = nc.def_group("child")
+  child.def_dim("station", 10)       # defined in child
+
+  # temp uses one root-level dim and one child-local dim
+  child.def_var("temp", :float, ["time", "station"])
+end
+
+NC::File.open("nested.nc") do |nc|
+  t = nc["/child/temp"]
+  t.shape             # => [24, 10]
+  t.dims.map(&:name)  # => ["time", "station"]
+  t.dims[0].group.path   # => "/"        (inherited from root)
+  t.dims[1].group.path   # => "/child"   (defined in child)
+end
+```
+
+**Per-group `dims`** returns only that group's local dims (not inherited):
+
+```ruby
+nc.dims.keys                        # => ["time"]
+nc.group("child").dims.keys         # => ["station"]  (not "time")
+```
+
+Use `group.resolve_dim("time")` if you explicitly want the ancestor-walked lookup:
+
+```ruby
+nc.group("child").resolve_dim("time")     # => the Dim from root
+nc.group("child").resolve_dim("bogus")    # => raises KeyError
+```
+
+## Per-group attributes
+
+Every group has its own global-attribute set (netcdf-4 changes `NC_GLOBAL` from a single set to per-group). `def_att` / `atts` / `att` on a Group operate on that set:
+
+```ruby
+NC::File.create("attrs.nc", netcdf4: true) do |nc|
+  nc.def_att("title", "Root title")
+
+  ocean = nc.def_group("ocean")
+  ocean.def_att("title", "Ocean subgroup title")
+  ocean.def_att("depth_convention", "positive down")
+end
+
+NC::File.open("attrs.nc") do |nc|
+  nc.att("title")                              # => "Root title"
+  nc.group("ocean").att("title")               # => "Ocean subgroup title"
+  nc.group("ocean").att("depth_convention")    # => "positive down"
+  nc.att("depth_convention")                   # => nil (not on root)
+end
+```
+
+## Codecs are inherited from the root
+
+The codec is a whole-file policy — `Conventions` at the root determines which codec applies to every variable, including those in subgroups. `Group#codec` delegates to the File.
+
+```ruby
+NC::File.create("cf_groups.nc", netcdf4: true) do |nc|
+  nc.def_att("Conventions", "CF-1.7")
+  nc.def_dim("time", 24)
+
+  ocean = nc.def_group("ocean")
+  ocean.def_var("time_utc", :int, ["time"],
+                units: "hours since 2022-01-01T00:00:00Z")
+  ocean["time_utc"] = CArray.time_series("2022-01-01T00:00:00Z", count: 24, unit: :h)
+end
+
+NC::File.open("cf_groups.nc") do |nc|
+  nc.codec.is_a?(NC::Codec::CF)              # => true
+  nc.group("ocean").codec.equal?(nc.codec)   # => true (same instance)
+
+  t = nc["/ocean/time_utc"].to_ca
+  t.is_a?(CATime)                            # => true (decoded via CF)
+  t[3].to_s                                  # => "2022-01-01T03:00:00Z"
+end
+```
+
+## Introspection reference
+
+| Method | Returns |
+|---|---|
+| `group.name` | `"foo"` (or `"/"` for root) |
+| `group.path` | `"/foo/bar"` (full hierarchy path) |
+| `group.parent` | parent Group, or `nil` for root |
+| `group.root?` | Boolean |
+| `group.file` | the enclosing File (root Group) |
+| `group.ncid` | raw group ncid (int) |
+| `group.dims` | `{String => Dim}` — this group only |
+| `group.vars` | `{String => Var}` — this group only |
+| `group.groups` | `{String => Group}` — direct children |
+| `group.atts` | `{String => value}` (frozen) — this group's globals |
+| `group.dim(name)` / `.var(name)` / `.group(name)` | one lookup |
+| `group.dim?(name)` / `.var?(name)` / `.group?(name)` | Boolean |
+| `group.att(name)` | one attribute value |
+| `group.resolve_dim(name)` | walk up ancestors |
+| `group.codec` | codec (same as `file.codec`) |