Merge pull request #33 from CAB-LAB/static_vars

Static vars

NEWS.md

@@ -0,0 +1,11 @@
+# News
+
+## v0.2
+
+* a list of pre-defined lon-lat boxes was added that can be accessed when calling `getCubeData`, so for example `getCubeData(c,region="Germany")` will extract a Germany from the Cube.
+* Support for masks was extended, this includes multiple changes:
+  - every cube now has a `properties` field, which contains a `Dict{String,Any}` where additional cube propertyies can be stored
+  - if an Integer-valued cube is used as a categorical mask one can add a Dict containg the mapping from value to label name to the cubes properties, eg `c.properties["labels"]=Dict(1=>"low",2=>"high")`
+  - `plotMAP` will respect the defined label properties and use the labels for its legend
+  - if a labeled cube is used in the `by` argument when fitting an `OnlineStat`, the output axis is automatically created
+  - accessing a static variable (currently only water_mask or country_mask) through `getCubeData` will by default only return the first time step

docs/src/analysis.md

@@ -82,10 +82,11 @@ statistics by a certain axis, it has to be specified using the `by` keyword argu
 `by` accepts a vector of axes types and up to one datacube that can serve as a mask. If such
 a data cube is supplied, the statistics are split by the unique values in the mask. One can pass
 a function `cfun` that transforms the mask values into an index in the range `1..N` that defines the   
-index where the new value is going to be put to. If a mask is supplied, one also needs to supply an
+index where the new value is going to be put to. If a mask is supplied, it must have either a `labels` property,
+which is a `Dict{T,String}` mapping the numerical mask value to the value name. Alternatively on can supply an
 `outAxis` argument that describes the resulting output axis.
 
-This all gets clearer with a little example. suppose we want to calculate the mean of GPP, NEE and TER
+This all gets clearer with two small examples. suppose we want to calculate the mean of GPP, NEE and TER
 under the condition that Tair<280K and Tair>280K over all time steps and grid cells. This is achieved through the
 following lines of code:
 
@@ -129,3 +130,17 @@ b=IOBuffer()
 show(b,MIME"text/html"(),p)
 Documenter.Documents.RawHTML(takebuf_string(b))
 ```
+
+A second example would be that we want to calculate averages of the fluxes according to
+a country mask.
+
+```julia
+import OnlineStats
+vars  = ["gross_primary_productivity","net_ecosystem_exchange","terrestrial_ecosystem_respiration"]
+m     = getCubeData(ds,variable="country_mask",longitude=lons,latitude=lats)
+cube  = getCubeData(ds,variable=vars,longitude=lons,latitude=lats)
+
+mT    = mapCube(OnlineStats.Mean,cube,by=[m,VariableAxis], cfun=splitTemp, outAxis=outAxis)
+```
+
+This will split the cube by country and variable and compute averages over the input variables.

src/CubeAPI/CachedArrays.jl

@@ -337,12 +337,18 @@ write_subblock!{T,N}(x::MaskedCacheBlock{T,N},y::Any,block_size::CartesianIndex{
 
 function write_subblock!{T,N}(x::MaskedCacheBlock{T,N},y::TempCube{T,N},block_size::CartesianIndex{N})
     filename=joinpath(y.folder,tofilename(x.position))
-    #println("Writing to file $filename")
     ncwrite(x.data,filename,"cube")
     ncwrite(x.mask,filename,"mask")
     ncclose(filename)
     x.iswritten=false
 end
+function write_subblock!{T}(x::MaskedCacheBlock{T,0},y::TempCube{T,0},block_size::CartesianIndex{0})
+    filename=joinpath(y.folder,tofilename(x.position))
+    ncwrite([x.data[1]],filename,"cube")
+    ncwrite([x.mask[1]],filename,"mask")
+    ncclose(filename)
+    x.iswritten=false
+end
 function read_subblock!{T,N}(x::MaskedCacheBlock{T,N},y::TempCube{T,N},block_size::CartesianIndex{N})
     if block_size==y.block_size
         filename=joinpath(y.folder,tofilename(x.position))
@@ -356,6 +362,19 @@ function read_subblock!{T,N}(x::MaskedCacheBlock{T,N},y::TempCube{T,N},block_siz
     end
 end
 
+function read_subblock!{T}(x::MaskedCacheBlock{T,0},y::TempCube{T,0},block_size::CartesianIndex{0})
+  filename=joinpath(y.folder,tofilename(x.position))
+  vc=NetCDF.open(filename,"cube")
+  vm=NetCDF.open(filename,"mask")
+  x.data[1]=vc[1]
+  x.mask[1]=vm[1]
+  ncclose(filename)
+end
+function getSubRange{T,S<:MaskedCacheBlock}(c::CachedArray{T,0,S};write=false)
+  c.currentblocks[1].iswritten=write
+  (c.currentblocks[1].data,c.currentblocks[1].mask)
+end
+
 function sync(c::CachedArray)
     for b in c.currentblocks
         if b.iswritten