update docs

README.md

@@ -48,10 +48,10 @@ For interactive use, the following commands (without ending semicolon) display t
 
 ```julia
 using NCDatasets
-ds = Dataset("file.nc")
+ds = NCDataset("file.nc")
 ```
 
-This creates the central structure of NCDatasets.jl, `Dataset`, which represents the contents of the netCDF file (without immediatelly loading everything in memory). `NCDataset` is an alias for `Dataset`.
+This creates the central structure of NCDatasets.jl, `NCDataset`, which represents the contents of the netCDF file (without immediatelly loading everything in memory). `NCDataset` is an alias for `Dataset`.
 
 The following displays the information just for the variable `varname`:
 
@@ -89,7 +89,7 @@ Loading a variable with known structure can be achieved by accessing the variabl
 
 ```julia
 # The mode "r" stands for read-only. The mode "r" is the default mode and the parameter can be omitted.
-ds = Dataset("/tmp/test.nc","r")
+ds = NCDataset("/tmp/test.nc","r")
 v = ds["temperature"]
 
 # load a subset
@@ -110,15 +110,15 @@ close(ds)
 In the example above, the subset can also be loaded with:
 
 ```julia
-subdata = Dataset("/tmp/test.nc")["temperature"][10:30,30:5:end]
+subdata = NCDataset("/tmp/test.nc")["temperature"][10:30,30:5:end]
 ```
 
 This might be useful in an interactive session. However, the file `test.nc` is not directly closed (closing the file will be triggered by Julia's garbage collector), which can be a problem if you open many files. On Linux the number of opened files is often limited to 1024 (soft limit). If you write to a file, you should also always close the file to make sure that the data is properly written to the disk.
 
 An alternative way to ensure the file has been closed is to use a `do` block: the file will be closed automatically when leaving the block.
 
 ```julia
-data = Dataset(filename,"r") do ds
+data = NCDataset(filename,"r") do ds
     ds["temperature"][:,:]
 end # ds is closed
 ```
@@ -132,7 +132,7 @@ using NCDatasets
 using DataStructures
 # This creates a new NetCDF file /tmp/test.nc.
 # The mode "c" stands for creating a new file (clobber)
-ds = Dataset("/tmp/test.nc","c")
+ds = NCDataset("/tmp/test.nc","c")
 
 # Define the dimension "lon" and "lat" with the size 100 and 110 resp.
 defDim(ds,"lon",100)
@@ -164,7 +164,7 @@ It is also possible to create the dimensions, the define the variable and set it
 
 ```julia
 using NCDatasets
-ds = Dataset("/tmp/test2.nc","c")
+ds = NCDataset("/tmp/test2.nc","c")
 data = [Float32(i+j) for i = 1:100, j = 1:110]
 v = defVar(ds,"temperature",data,("lon","lat"))
 close(ds)
@@ -178,7 +178,7 @@ to open it with the `"a"` option. Here, for example, we add a global attribute *
 file created in the previous step.
 
 ```julia
-ds = Dataset("/tmp/test.nc","a")
+ds = NCDataset("/tmp/test.nc","a")
 ds.attrib["creator"] = "your name"
 close(ds);
 ```

docs/src/dataset.md

@@ -30,6 +30,22 @@ Otherwise, we attempt to use standard structures from the Julia standard library
 
 ## Groups
 
+A NetCDF group is a dataset (with variables, attributes, dimensions and sub-groups) and
+can be arbitrarily nested.
+A group is created with `defGroup` and accessed via the `group` property of
+a `NCDataset`.
+
+```julia
+# create the variable "temperature" inside the group "forecast"
+ds = NCDataset("results.nc", "c");
+ds_forecast = defGroup(ds,"forecast")
+defVar(ds_forecast,"temperature",randn(10,11,12),("lon","lat","time"))
+
+# load the variable "temperature" inside the group "forecast"
+forecast_temp = ds.group["forecast"]["temperature"][:,:,:]
+close(ds)
+```
+
 ```@docs
 defGroup
 getindex(g::NCDatasets.Groups,groupname::AbstractString)

docs/src/index.md

@@ -1,6 +1,12 @@
 # NCDatasets.jl
 
-Documentation for NCDatasets.jl, a Julia package for loading and writing NetCDF ([Network Common Data Form](https://www.unidata.ucar.edu/software/netcdf/)) files.
+Documentation for [NCDatasets.jl](https://github.com/Alexander-Barth/NCDatasets.jl), a Julia package for loading and writing NetCDF ([Network Common Data Form](https://www.unidata.ucar.edu/software/netcdf/)) files.
+NCDatasets.jl implements the for the NetCDF format the interface defined
+in [CommonDataModel.jl](https://github.com/JuliaGeo/CommonDataModel.jl).
+All functions defined by CommonDataModel.jl are also available for NetCDF data, including:
+* virtually concatenating multiple files along a given dimension
+* create a virtual subset (`view`) by indices or by values of coordinate variables (`CommonDataModel.select`, `CommonDataModel.@select`)
+* group, map and reduce (with `mean`, standard deviation `std`, ...) a variable (`CommonDataModel.groupby`, `CommonDataModel.@groupby`) and rolling reductions like running means `CommonDataModel.rolling`). 
 
 ## Installation
 
@@ -11,6 +17,8 @@ using Pkg
 Pkg.add("NCDatasets")
 ```
 
+Or by typing `]add NCDatasets` using the package manager mode.
+
 ### Latest development version
 
 If you want to try the latest development version, again go into package manager mode and simply type
@@ -30,9 +38,9 @@ To get started quickly see the [Quickstart](@ref) section. Otherwise see the fol
 * [Attributes](@ref) : accessing/creating NetCDF attributes
 * See [Performance tips](@ref performance_tips), [Known issues](@ref), [Experimental features](@ref) for more information.
 
-## Quickstart
+## Quick start
 
-This is a quickstart guide that outlines basic loading, reading, etc. usage.
+This is a quick start guide that outlines basic loading, reading, etc. usage.
 For more details please see the individual pages of the documentation.
 
 
@@ -183,9 +191,9 @@ using NCDatasets
 using DataStructures
 data = [Float32(i+j) for i = 1:100, j = 1:110]
 
-Dataset("/tmp/test2.nc","c",attrib = OrderedDict("title" => "this is a test file")) do ds
+NCDataset("/tmp/test2.nc","c",attrib = OrderedDict("title" => "this is a test file")) do ds
     # Define the variable temperature. The dimension "lon" and "lat" with the
-    # size 100 and 110 resp are implicetly created
+    # size 100 and 110 resp are implicitly created
     defVar(ds,"temperature",data,("lon","lat"), attrib = OrderedDict(
            "units" => "degree Celsius",
            "comments" => "this is a string attribute with Unicode Ω ∈ ∑ ∫ f(x) dx"
@@ -209,10 +217,12 @@ close(ds);
 
 The utility function [`ncgen`](https://alexander-barth.github.io/NCDatasets.jl/stable/#NCDatasets.ncgen)
 generates the Julia code that would produce a netCDF file with the same metadata as a template netCDF file.
-It is thus similar to the [command line tool `ncgen`](https://www.unidata.ucar.edu/software/netcdf/netcdf/ncgen.html).
+It is thus similar to the [command line tool `ncgen`](https://www.unidata.ucar.edu/software/netcdf/netcdf/ncgen.html)
+which can generate C or Fortran code from the output of [`ncdump`](https://www.unidata.ucar.edu/software/netcdf/netcdf/ncdump.html).
 
 ```julia
-# download example file
+using Downloads: download
+# download an example file
 ncfile = download("https://www.unidata.ucar.edu/software/netcdf/examples/sresa1b_ncar_ccsm3-example.nc")
 # generate Julia code
 ncgen(ncfile)
@@ -240,8 +250,8 @@ ncarea.attrib["units"] = "meter2";
 
 ### Get one or several variables by specifying the value of an attribute
 
-The variable names are not always standardized. For example, for the longitude we can
-find: `lon`, `LON`, `longitude`, ...
+The variable names are not always standardized. For example, the longitude can
+be named: `lon`, `LON`, `longitude`, `łøñgitüdè`, ...
 
 The solution implemented in the function `varbyattrib` consists in searching for the
 variables that have specified value for a given attribute.
@@ -257,6 +267,24 @@ attribute `standard_name` equal to `"longitude"` one can do the following:
 data = varbyattrib(ds, standard_name = "longitude")[1][:]
 ```
 
+As looking-up a variable by standard name is quite common, one can also use the
+`@CF_str` macro and index the dataset using a string prefixed by `CF`.
+
+```julia
+using NCDatasets: @CF_str
+ds[CF"longitude"]
+```
+
+If multiple variables share the same standard name, such statements `ds[CF"longitude"]` are ambiguous and an error is returned.
+This is typically the case for e.g. ocean models like ROMS where different variables (u, v and w velocity) are defined on different staggered grids (i.e. shifted by a half grid-cell from each other).
+To disambiguate, one can first index the dataset `ds` with main data variable (e.g. vertical velocity) and then again extract the longitude associated to the data variable.
+
+```julia
+ds[CF"upward_sea_water_velocity"][CF"longitude"]
+```
+
+Such statement is no longer ambiguous as from the dimension names it is clear which longitude has to be accessed.
+
 ### Load a file with unknown structure
 
 If the structure of the netCDF file is not known before-hand, the program must check if a variable or attribute exists (with the `haskey` function) before loading it or alternatively place the loading in a `try`-`catch` block.

docs/src/variables.md

@@ -35,6 +35,7 @@ A scalar variable can be loaded using `[]`, for example:
 ```julia
 using NCDatasets
 NCDataset("test_scalar.nc","c") do ds
+    # the list of dimension names is simple `()` as a scalar does not have dimensions
     defVar(ds,"scalar",42,())
 end