A quick starting guide to get you using cube_helper
in a matter of minutes.
To load a cube from a directory of netCDF files:
>>> import cube_helper as ch
>>> cube = ch.load('/path/to/cmip/data/HadGEM3-GC31-LL/piControl/r1i1p1f1/Amon/tasmin/gn/v20190628')
To load a cube from files that are matched by a pattern:
>>> import glob
>>> filenames = glob.glob('/path/to/cmip/data/tasmin*.nc')
>>> cube = ch.load(filenames)
To load a cube from a single file (or files) then include the full path of each required file in a list:
>>> cube = ch.load(['/path/to/cmip/data/tasmin_Amon_HadGEM3-GC31-LL_piControl_r1i1p1f1_gn_185001-194912.nc'])
>>> import iris
>>> longitude_constraint = iris.Constraint(longitude = lambda cell : cell > 0 and cell < 180)
>>> cube = ch.load('/path/to/cmip/data/HadGEM3-GC31-LL/piControl/r1i1p1f1/Amon/tasmin/gn/v20190628', constraints=longitude_constraint)
Sometimes, in production systems you may not need the full output from cube_helper. You can load cubes and suppress output with ch.muffle_logger()
. You can reset to the default logging settings with ch.reset_logger()
>>> cube = ch.load('/path/to/cmip/data/output1/ICHEC/EC-EARTH/historical/mon/atmos/Amon/r1i1p1/v20131231/tas/')
cube attributes differ:
tracking_id, history and creation_date attibutes inconsistent
cube time coordinates differ:
time start date inconsistent
Deleting tracking_id, history and creation_date attributes from cubes
New time origin set to days since 1850-01-01 00:00:00
>>> ch.muffle_logger()
>>> cube = ch.load('/path/to/cmip/data/output1/ICHEC/EC-EARTH/historical/mon/atmos/Amon/r1i1p1/v20131231/tas/', silent=True)
>>> ch.reset_logger()
>>> cube = ch.load('/path/to/cmip/data/output1/ICHEC/EC-EARTH/historical/mon/atmos/Amon/r1i1p1/v20131231/tas/')
cube attributes differ:
tracking_id, history and creation_date attibutes inconsistent
cube time coordinates differ:
time start date inconsistent
Deleting tracking_id, history and creation_date attributes from cubes
New time origin set to days since 1850-01-01 00:00:00
If you are dealing with cubes that have already been loaded, for CubeLists and list of loaded cubes.
>>> cubes
[<iris 'Cube' of air_temperature / (K) (time: 1200; latitude: 144; longitude: 192)>,
<iris 'Cube' of air_temperature / (K) (time: 1200; latitude: 144; longitude: 192)>,
<iris 'Cube' of air_temperature / (K) (time: 1200; latitude: 144; longitude: 192)>,
<iris 'Cube' of air_temperature / (K) (time: 1200; latitude: 144; longitude: 192)>,
<iris 'Cube' of air_temperature / (K) (time: 1200; latitude: 144; longitude: 192)>]
>>> cube = ch.concatenate(cubes)
Deleting history, creation_date, and tracking_id attributes from cubes
>>> cube
<iris 'Cube' of air_temperature / (K) (time: 6000; latitude: 144; longitude: 192)>
Add a categorical coordinate to an iterable of iris cubes or a standalone cube.
>>> cube
<iris 'Cube' of air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)>
>>> cube = ch.add_categorical(cube, 'clim_season')
>>> print(cube)
air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)
Dimension coordinates:
time x - -
latitude - x -
longitude - - x
Auxiliary coordinates:
clim_season x - -
Attributes:
CDI: Climate Data Interface version 1.4.4 (http://code.zmaw.de/projects/cdi...
CDO: Climate Data Operators version 1.4.4 (http://code.zmaw.de/projects/cdo...
Conventions: CF-1.4
associated_files: baseURL: http://cmip-pcmdi.llnl.gov/CMIP5/dataLocation gridspecFile: gridspec_atmos_fx_EC-EARTH_historical_r0i0p0.nc...
branch_time: 2125.0
cmor_version: 2.8.0
comment: Equilibrium reached after preindustrial spin-up after which data were output...
contact: Alastair McKinstry <alastair.mckinstry@ichec.ie>
experiment: historical
experiment_id: historical
forcing: Nat,Ant
frequency: mon
grid_type: gaussian
initialization_method: 1
institute_id: ICHEC
institution: EC-Earth (European Earth System Model)
model_id: EC-EARTH
modeling_realm: atmos
original_name: 2T
parent_experiment: pre-industrial control
parent_experiment_id: piControl
parent_experiment_rip: r1i1p1
physics_version: 1
product: output
project_id: CMIP5
realization: 1
references: Model described by Hazeleger et al. (Bull. Amer. Meteor. Soc., 2010, 91,...
table_id: Table Amon (26 July 2011) b26379e76858ab98b927917878a63d01
title: EC-EARTH model output prepared for CMIP5 historical
Cell methods:
mean: time (3 hours)
>>> cube
<iris 'Cube' of air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)>
>>> cube = ch.add_categorical(cube, ['clim_season', 'season_year'])
>>> print(cube)
air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)
Dimension coordinates:
time x - -
latitude - x -
longitude - - x
Auxiliary coordinates:
clim_season x - -
season_year x - -
Attributes:
CDI: Climate Data Interface version 1.4.4 (http://code.zmaw.de/projects/cdi...
CDO: Climate Data Operators version 1.4.4 (http://code.zmaw.de/projects/cdo...
Conventions: CF-1.4
associated_files: baseURL: http://cmip-pcmdi.llnl.gov/CMIP5/dataLocation gridspecFile: gridspec_atmos_fx_EC-EARTH_historical_r0i0p0.nc...
branch_time: 2125.0
cmor_version: 2.8.0
comment: Equilibrium reached after preindustrial spin-up after which data were output...
contact: Alastair McKinstry <alastair.mckinstry@ichec.ie>
experiment: historical
experiment_id: historical
forcing: Nat,Ant
frequency: mon
grid_type: gaussian
initialization_method: 1
institute_id: ICHEC
institution: EC-Earth (European Earth System Model)
model_id: EC-EARTH
modeling_realm: atmos
original_name: 2T
parent_experiment: pre-industrial control
parent_experiment_id: piControl
parent_experiment_rip: r1i1p1
physics_version: 1
product: output
project_id: CMIP5
realization: 1
references: Model described by Hazeleger et al. (Bull. Amer. Meteor. Soc., 2010, 91,...
table_id: Table Amon (26 July 2011) b26379e76858ab98b927917878a63d01
title: EC-EARTH model output prepared for CMIP5 historical
Cell methods:
mean: time (3 hours)
If the categoricals you are adding are part of a compound categorical, you can use special calls such as:
>>> cube
<iris 'Cube' of air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)>
>>> annual_seasonal_mean = ch.add_categorical(cube, 'annual_seasonal_mean')
>>> print(annual_seasonal_mean)
air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)
Dimension coordinates:
time x - -
latitude - x -
longitude - - x
Auxiliary coordinates:
clim_season x - -
season_year x - -
Attributes:
CDI: Climate Data Interface version 1.4.4 (http://code.zmaw.de/projects/cdi...
CDO: Climate Data Operators version 1.4.4 (http://code.zmaw.de/projects/cdo...
Conventions: CF-1.4
associated_files: baseURL: http://cmip-pcmdi.llnl.gov/CMIP5/dataLocation gridspecFile: gridspec_atmos_fx_EC-EARTH_historical_r0i0p0.nc...
branch_time: 2125.0
cmor_version: 2.8.0
comment: Equilibrium reached after preindustrial spin-up after which data were output...
contact: Alastair McKinstry <alastair.mckinstry@ichec.ie>
experiment: historical
experiment_id: historical
forcing: Nat,Ant
frequency: mon
grid_type: gaussian
initialization_method: 1
institute_id: ICHEC
institution: EC-Earth (European Earth System Model)
model_id: EC-EARTH
modeling_realm: atmos
original_name: 2T
parent_experiment: pre-industrial control
parent_experiment_id: piControl
parent_experiment_rip: r1i1p1
physics_version: 1
product: output
project_id: CMIP5
realization: 1
references: Model described by Hazeleger et al. (Bull. Amer. Meteor. Soc., 2010, 91,...
table_id: Table Amon (26 July 2011) b26379e76858ab98b927917878a63d01
title: EC-EARTH model output prepared for CMIP5 historical
Cell methods:
mean: time (3 hours)
Returns an aggregated cube.
>>> cube
<iris 'Cube' of air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)>
>>> cube = ch.aggregate_categorical(cube, 'clim_season')
>>> print(cube)
air_temperature / (K) (time: 4; latitude: 160; longitude: 320)
Dimension coordinates:
time x - -
latitude - x -
longitude - - x
Auxiliary coordinates:
clim_season x - -
Attributes:
CDI: Climate Data Interface version 1.4.4 (http://code.zmaw.de/projects/cdi...
CDO: Climate Data Operators version 1.4.4 (http://code.zmaw.de/projects/cdo...
Conventions: CF-1.4
associated_files: baseURL: http://cmip-pcmdi.llnl.gov/CMIP5/dataLocation gridspecFile: gridspec_atmos_fx_EC-EARTH_historical_r0i0p0.nc...
branch_time: 2125.0
cmor_version: 2.8.0
comment: Equilibrium reached after preindustrial spin-up after which data were output...
contact: Alastair McKinstry <alastair.mckinstry@ichec.ie>
experiment: historical
experiment_id: historical
forcing: Nat,Ant
frequency: mon
grid_type: gaussian
initialization_method: 1
institute_id: ICHEC
institution: EC-Earth (European Earth System Model)
model_id: EC-EARTH
modeling_realm: atmos
original_name: 2T
parent_experiment: pre-industrial control
parent_experiment_id: piControl
parent_experiment_rip: r1i1p1
physics_version: 1
product: output
project_id: CMIP5
realization: 1
references: Model described by Hazeleger et al. (Bull. Amer. Meteor. Soc., 2010, 91,...
table_id: Table Amon (26 July 2011) b26379e76858ab98b927917878a63d01
title: EC-EARTH model output prepared for CMIP5 historical
Cell methods:
mean: time (3 hours)
mean: clim_season
Aggregates and extracts with a given constraint.
>>> cube
<iris 'Cube' of air_temperature / (K) (time: 1919; latitude: 160; longitude: 320)>
>>> tdelta_3mth = datetime.timedelta(hours=3*28*24.0)
>>> spans_three_months = lambda t: (t.bound[1] - t.bound[0]) > tdelta_3mth
>>> three_months_bound = iris.Constraint(time=spans_three_months)
>>> annual_seasonal_mean = ch.extract_categorical(cube, 'annual_seasonal_mean', three_months_bound)
>>> annual_seasonal_mean
<iris 'Cube' of air_temperature / (K) (time: 639; latitude: 160; longitude: 320)>
To load from a list of fname strings. Useful when combining datasets.
>>> from glob import glob
>>> fnames = glob('/path/to/cmip/data/output1/ICHEC/EC-EARTH/historical/mon/atmos/Amon/r1i1p1/v20131231/tas/*.nc')
>>> cube = ch.load(fnames)
Extracts a constraint from a cube. Time constraints work irrespective of whether the cube's time coordinate has bounds or not.
>>> cube
<iris 'Cube' of air_temperature / (K) (time: 1752; latitude: 145; longitude: 192)>
>>> constraint = iris.Constraint(time=iris.time.PartialDateTime(month=2))
>>> extracted_cube = ch.extract(cube, constraint)
>>> extracted_cube
<iris 'Cube' of air_temperature / (K) (time: 146; latitude: 145; longitude: 192)>
There are some errors in CMIP data that are known about and can be fixed automatically. For details on the errors that can currently be fixed please see the :pycube_helper.fix_known_issues
documentation.
>>> cube = ch.load('/path/to/data/CMIP6/CMIP/CAS/FGOALS-f3-L/historical/r1i1p1f1/day/psl/gr/v20191019/')
>>> cube.coord('latitude').is_contiguous()
False
>>> ch.fix_known_issues(cube)
Applying FixCmip6CasFgoals. Fixing latitude and longitude bounds.
>>> cube.coord('latitude').is_contiguous()
True