cloudmetrics
The cloudmetrics
package contains python routines to compute metrics
from 2D cloud fields to characterise cloud patterns in these fields. Most
methods operate on a cloudmask
(i.e. a boolean truefalse field)
indicating where clouds exist, some work on individually labelled (with a
unique integer ID) cloud objects (which can be produced from a cloudmask) and
finally some work on 2D cloud scalarfields (defining for example the
cloudliquid water or cloudtop height).
NOTE: the
cloudmetrics
package contained in this repository is refactored from work published in Janssens et al 2021, this was done to make the routines implemented more accessible by external tools and to ensure consistency. Not all functionality has been retained or fully refactored, in particular functionality to allow for bulkprocessing of input files is in the cloudmetricspipline package. Progress on the refactoring can be followed in issue #20. The version published in Janssens et al 2021 is available tagged as version v0.1.0.
Implemented metrics
The table below gives an overview over which metrics are avaiable in the
cloudmetrics
package and what input each metric takes.
function within cloudmetrics

mask 
object_labels 
scalar_field 

mask.cloud_fraction 
✔️  
mask.fractal_dimension 
✔️  
mask.open_sky 
✔️  
mask.orientation 
✔️  
mask.network_nn_dist 
TODO  
mask.cop 
✔️†  ✔️  
mask.csd 
TODO  TODO  
objects.iorg 
✔️†  ✔️  
objects.max_length_scale 
✔️†  ✔️  
objects.mean_eccentricity 
✔️†  ✔️  
objects.mean_length_scale 
✔️†  ✔️  
objects.mean_perimeter_length 
✔️†  ✔️  
objects.rdf 
TODO  TODO  
objects.scai 
✔️†  ✔️  
scalar.spectral_anisotropy #1 
✔️  
scalar.spectral_length_median #1 
✔️  
scalar.spectral_length_moment, #1 
✔️  
scalar.spectral_slope #1 
✔️  
scalar.spectral_slope_binned #1 
✔️  
scalar.woi1 
✔️  
scalar.woi2 
✔️  
scalar.woi3 
✔️  
scalar.mean 
optional  ✔️  
scalar.var 
optional  ✔️  
scalar.std 
optional  ✔️  
scalar.skew 
optional  ✔️  
scalar.kurtosis 
optional  ✔️ 
†: for convenience objectbased scalars are also made avaiable to operate
directly on masks, for example objects.max_length_scale(object_labels=...)
can be called with a mask as mask.max_object_length_scale(mask=...)
and
objects.iorg(object_labels=...)
can be called with
mask.iorg_objects(mask=...)
.
#1: spectral metrics currently operate on the relevant power spectral densities, which must first be computed:
wavenumbers, psd_1d_radial, psd_1d_azimuthal = scalar.compute_spectra(...)
spectral_length_moment = scalar.spectral_length_moment(wavenumbers, psd_1d_radial)
Alternatively, all spectral metrics can be computed simultaneously following the
standard convention with spectral_metrics = scalar.compute_all_spectral(scalar_field)
.
need refactoring to take scalar_field
as input
Installation
To install the most recent version of cloudmetrics
from pypi you can use pip
:
$> pip install cloudmetrics
If you plan to add/modify cloudmetrics
(contribution via pullrequests are
very welcome!) you should check out the development
notes
for how to get set up with a local copy of the codebase.
Usage
To use the cloudmetrics
package simply import cloudmetrics
and use the
metric function you are interested in:
import cloudmetrics
iorg = cloudmetrics.mask.iorg_objects(mask=da_cloudmask, periodic_domain=False)
As you can see in the table above the metrics are organised by the input they take, either object masks, labelledobject arrays and/or 2D scalar fields you want to perform reductions on.
Note on periodic domains: internally cloudmetrics
represents objects on
periodic domains by doubling the xysize of any input mask provided, and moving
any objects that straddle the boundary to ensure they are spatially contiguous.
This means that all functions which take 2D arrays of objectlabels as input
assume that all labelled objects are spatially contiguous and that the provided
input is actually 2*nx x 2*ny
(for an actual input domain spanning nx
by
nx
). All metric functions that operate on masks handle the domaindoubling
internally and so do not require any modification to the masks before calling.