From 2fe4efb9dd7328cc0801bccd376e3dd950908819 Mon Sep 17 00:00:00 2001 From: Alexander Barth Date: Wed, 20 Mar 2024 22:03:39 +0100 Subject: [PATCH] Reorder examples in README.md (thanks @boriskaus) --- README.md | 125 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 66 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index def13aae..d030d655 100644 --- a/README.md +++ b/README.md @@ -35,11 +35,59 @@ Pkg.add("NCDatasets") This Manual is a quick introduction in using NCDatasets.jl. For more details you can read the [stable](https://alexander-barth.github.io/NCDatasets.jl/stable/) or [latest](https://alexander-barth.github.io/NCDatasets.jl/latest/) documentation. +* [Create a netCDF file](#create-a-netcdf-file) * [Explore the content of a netCDF file](#explore-the-content-of-a-netcdf-file) * [Load a netCDF file](#load-a-netcdf-file) -* [Create a netCDF file](#create-a-netcdf-file) * [Edit an existing netCDF file](#edit-an-existing-netcdf-file) +## Create a netCDF file + +The following gives an example of how to create a netCDF file by defining dimensions, variables and attributes. + +```julia +using NCDatasets +using DataStructures: OrderedDict +# This creates a new NetCDF file called file.nc. +# The mode "c" stands for creating a new file (clobber) +ds = NCDataset("file.nc","c") + +# Define the dimension "lon" and "lat" with the size 100 and 110 resp. +defDim(ds,"lon",100) +defDim(ds,"lat",110) + +# Define a global attribute +ds.attrib["title"] = "this is a test file" + +# Define the variables temperature with the attribute units +v = defVar(ds,"temperature",Float32,("lon","lat"), attrib = OrderedDict( + "units" => "degree Celsius", + "scale_factor" => 10, +)) + +# add additional attributes +v.attrib["comments"] = "this is a string attribute with Unicode Ω ∈ ∑ ∫ f(x) dx" + +# Generate some example data +data = [Float32(i+j) for i = 1:100, j = 1:110]; + +# write a single column +v[:,1] = data[:,1]; + +# write a the complete data set +v[:,:] = data; + +close(ds) +``` + +It is also possible to create the dimensions, the define the variable and set its value with a single call to `defVar`: + +```julia +using NCDatasets +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) +``` ## Explore the content of a netCDF file Before reading the data from a netCDF file, it is often useful to explore the list of variables and attributes defined in it. @@ -63,24 +111,28 @@ while to get the global attributes you can do: ```julia ds.attrib ``` -which produces a listing like: + +`NCDataset("file.nc")` produces a listing like: ``` Dataset: file.nc Group: / Dimensions - time = 115 + lon = 100 + lat = 110 Variables - time (115) - Datatype: Float64 - Dimensions: time + temperature (100 × 110) + Datatype: Float32 (Float32) + Dimensions: lon × lat Attributes: - calendar = gregorian - standard_name = time - units = days since 1950-01-01 00:00:00 -[...] + units = degree Celsius + scale_factor = 10 + comments = this is a string attribute with Unicode Ω ∈ ∑ ∫ f(x) dx + +Global attributes + title = this is a test file ``` ## Load a netCDF file @@ -89,7 +141,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 = NCDataset("/tmp/test.nc","r") +ds = NCDataset("file.nc","r") v = ds["temperature"] # load a subset @@ -99,7 +151,7 @@ subdata = v[10:30,30:5:end] data = v[:,:] # load all data ignoring attributes like scale_factor, add_offset, _FillValue and time units -data2 = v.var[:,:] +data2 = v.var[:,:]; # load an attribute @@ -110,7 +162,7 @@ close(ds) In the example above, the subset can also be loaded with: ```julia -subdata = NCDataset("/tmp/test.nc")["temperature"][10:30,30:5:end] +subdata = NCDataset("file.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. @@ -123,52 +175,7 @@ data = NCDataset(filename,"r") do ds end # ds is closed ``` -## Create a netCDF file - -The following gives an example of how to create a netCDF file by defining dimensions, variables and attributes. -```julia -using NCDatasets -using DataStructures -# This creates a new NetCDF file /tmp/test.nc. -# The mode "c" stands for creating a new file (clobber) -ds = NCDataset("/tmp/test.nc","c") - -# Define the dimension "lon" and "lat" with the size 100 and 110 resp. -defDim(ds,"lon",100) -defDim(ds,"lat",110) - -# Define a global attribute -ds.attrib["title"] = "this is a test file" - -# Define the variables temperature with the attribute units -v = defVar(ds,"temperature",Float32,("lon","lat"), attrib = OrderedDict( - "units" => "degree Celsius")) - -# add additional attributes -v.attrib["comments"] = "this is a string attribute with Unicode Ω ∈ ∑ ∫ f(x) dx" - -# Generate some example data -data = [Float32(i+j) for i = 1:100, j = 1:110] - -# write a single column -v[:,1] = data[:,1] - -# write a the complete data set -v[:,:] = data - -close(ds) -``` - -It is also possible to create the dimensions, the define the variable and set its value with a single call to `defVar`: - -```julia -using NCDatasets -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) -``` ## Edit an existing netCDF file @@ -178,7 +185,7 @@ to open it with the `"a"` option. Here, for example, we add a global attribute * file created in the previous step. ```julia -ds = NCDataset("/tmp/test.nc","a") +ds = NCDataset("file.nc","a") ds.attrib["creator"] = "your name" close(ds); ```