Fill-in userguide sections

[pp-mo]

More sections wanted, as existing "User Guide" section is a lot less complete than the "Getting Started" part.
User Guide currently looks like this:

• design principles
• (gap -- to be "data object descriptions")
• (gap -- to be "general topics")
• (gap -- to be "how-tos")

CURRENT PLANNED something like this ...

UserGuide : Data class descriptions

• Datasets
• Dimensions
• Variables
  • Data Arrays
• Attributes
  • Attribute Values
• NameMap

UserGuide : General topics

• Accessing attribute values ("reading + writing attributes")
• Dimensions
  • Dimension objects and Variable dimensions
  • Unlimited dimensions
  • Renaming Dimensions
• Data types
  • variable data
    • scaled data arrays
      • scale, offset and dtype conversion
    • masked data
    • string variables
  • attribute values
    • string attributes
• Insert, delete or rename objects
  • Adding
  • Deleting
  • Renaming
    • variables/attributes/groups : all quite easy
    • dimension rename
      • (utility)
      • NOTE on variable names (loss of dimension coordinates)
• File encoding
  • datatypes
  • compression
    • simple compression : scaling to smaller dtype
    • advanced compression : zlib, blosc etc
  • masking
  • chunking
• Data constructors
  • attributes are "special"
  • uses of NameMap
  • verbosity
• Equality testing (object ==)
• Serialisation

UserGuide : utility operations

• Dataset consistency
• comparison and difference
• structure copying
• dimension rename
• dimensional slicing
• remove unused dimensions

How-to examples

• change an attribute
• (( rename an attribute ))
• rename a variable ((or group)) ((or attribute))
• rename a dimension
• select a subset of variables
• delete an object (?any object = attribute, variable, group)
  • n.b. dimension is somewhat "special"
• move a variable ((or group))
• delete an attribute or variable ((or group))
• remove unused dimensions
• slice a dimension

[pp-mo]

More idea : extended description of threadlocking
Broadly stated..

• DON'T need if

  • only loading and saving with one format package

    • e.g.(1) load from netcdf, adjust and re-save to netcdf
    • e.g.(2) load with Iris, convert to Xarray, adjust, convert back and save (with Iris)

  • OR "just" converting data from Iris to or from Xarray, and using in the other package

    • e.g. load with Iris, adjust, convert to Xarray, calculate statistics with Xarray

• DO need if..

  • computing a combination of data loaded with different format packages
    • e.g. load data with Iris, convert to Xarray, combine with data loaded by Xarray, compute
  • loading from nc4/iris/xarray and saving to file with one of the others
    • e.g. load with Iris, adjust, convert to Xarray, calculate and save with Xarray
      • ((in this case, it should be safe to convert back to Iris and save from there))