search

Try2Code / cdo-bindings

Ruby/Python bindings for CDO
99 stars 37 forks source link
cdo netcdf python ruby

readme

Cdo.{rb,py} - Use Ruby/Python to access the power of CDO

Tests

Welcome to the scripting interfaces of CDO! This repository contains interfaces for Ruby and Python. If you are not sure whether this is useful or not, please have a look at: Why the .... should I use this???

What's going on

Currently this package is in a re-design phase. The target is a 2.0 release that will not be compatible with the existing release 1.5.x:

Installation

Releases are distributed via pypi and rubygems:

Requirements

Cdo.{rb,py} requires a working CDO binary and Ruby 2.x or Python 2.7/3.x

PLEASE NOTE: python-2.7 is unmaintained since January 2021 Many dependencies dropped support for 2.7 so I do manual testing with it,only.

Multi-dimensional arrays (numpy for python, narray for ruby) require addtional netcdf-io modules. These are scipy or python-netcdf4 for python and ruby-netcdf for ruby. Because scipy has some difficulties with netcdf, I dropped the support of it with release 1.5.0.

Thx to Alexander Winkler there is also an IO option for XArray.

Usage

You can find a lot of examples in the unit tests for both languages. Here are the direct links to the ruby tests and the python tests.

The following describes the basic features for both languages

Run operators

Befor calling operators, you have to create an object first:

    cdo = Cdo.new   #ruby
    cdo = Cdo()     #python

Please check the documentation for constructor paramaters. I try to have equal interfaces in both languages for all public methods.

Choose CDO binary

By default the cdo-bindings use the 'cdo' binary found in your $PATH variable. To change that, you can

Debugging

For debugging purpose, both interfaces provide a "debug" attribute. If it is set to a boolian true, the complete commands and the return values will be printed during execution

    cdo.debug = true    #ruby
    cdo.debug = True    #python

The default is false of cause.

File information

    cdo.infov(input: ifile)        #ruby
    cdo.showlevels(input: ifile)

    cdo.infov(input=ifile)         #python
    cdo.showlevels(input=ifile)

Operators with user defined regular output files

    cdo.timmin(input: ifile ,output: ofile)       #ruby
    cdo.timmin(input = ifile,output = ofile)      #python

By default the return value of each call is the name of the output files (no matter if its a temporary file or not)

Use temporary output files

If the output key is left out, one or more (depending on the operator) temporary files are generated and used as return value(s). In a regular script or a regularly closed interactive session, these files are removed at the end automatically.

    tminFile = cdo.timmin(input: ifile)  #ruby
    tminFile = cdo.timmin(input = ifile) #python

However these tempfiles remain if the session/script is killed with SIGKILL or if the bindings are used via Jupyter notebooks. Those session are usually long lasting and the heavy usage of tempfiles can easily fill the system tempdir - your system will become unusable then. The bindings offer two ways to cope with that

Operators with parameter

    cdo.remap([gridfile,weightfile],input:   ifile, output: ofile)   #ruby
    cdo.remap([gridfile,weightfile],input => ifile, output => ofile) #python

logging

    cdo = Cdo.new(logging: true, logFile: 'cdo_commands.log') #ruby
    cdo = Cdo(logging=True, logFile='cdo_commands.log')       #python

Set global CDO options

    cdo.copy(input:  ifile, output:  ofile,options:  "-f nc4")     #ruby
    cdo.copy(input = ifile, output = ofile,options = "-f nc4")     #python

Set environment variables

    cdo.splitname(input: ifile.join(' '),
                  output: 'splitTag',
                  env: {'CDO_FILE_SUFFIX' => '.nc'}) #or
    cdo.env = {'CDO_FILE_SUFFIX' => '.nc'}
    cdo.splitname(input = ' '.join(ifiles),
                  output =  'splitTag',
                  env={"CDO_FILE_SUFFIX": ".nc"})   #or
    cdo.env = {'CDO_FILE_SUFFIX': '.nc'}

Return multi-dimension arrays

    t = cdo.fldmin(:input => ifile,:returnArray => true).var('T').get  #rb, version <  1.2.0
    t = cdo.fldmin(:input => ifile,:returnCdf => true).var('T').get    #rb, version >= 1.2.0
    t = cdo.fldmin(:input => ifile,:returnArray => 'T')                #rb, version >= 1.2.0
    t = cdo.fldmin(input = ifile,returnArray = True).variables['T'][:] #py, version <  1.2.0
    t = cdo.fldmin(input = ifile,returnCdf = True).variables['T'][:]   #py, version >= 1.2.0
    t = cdo.fldmin(input = ifile,returnArray = 'T')                    #py, version >= 1.2.0

Other options are so-called masked arrays (use returnMaArray) for ruby and python and XArray/XDataset for python-only: use returnXArray or returnXDataset for that.

*) If you use scipy >= 0.14 as netcdf backend, you have to use following code instead to avoid possible segmentation faults:

    cdf = cdo.fldmin(input = ifile,returnCdf = True)
    temperatures = cdf.variables['T'][:]

More examples can be found in test/cdo-examples.rb and on the homepage

Avoid re-processing

If you do not want to re-compute files, you can set

For more information, please have a look at the unit tests.

Support, Issues, Bugs, ...

Please use the forum or ticket system of CDOs official web page: http://code.mpimet.mpg.de/projects/cdo

Changelog

Thanks to all contributors!

License

Cdo.{rb,py} makes use of the BSD-3-clause license