Add some examples here
As a command line tool, CIS has not been designed with a python API in mind. There are however some utility functions that may provide a useful start for those who wish to use CIS as a python library. For example, the functions in the base cis module provide a straightforward way to load your data. They can be easily import using, for example: from cis import read_data. One of the advantages of using CIS as a Python library is that you are able to perform multiple operations in one go, that is without writing to disk in between. In certain cases this may provide a significant speed-up.
Note
This section of the documentation expects a greater level of Python experience than the other sections. There are many helpful Python guides and tutorials available around the web if you wish to learn more.
The read_data function is a simple way to read a single gridded or ungridded data object (e.g. a NetCDF variable) from one or more files. CIS will determine the best way to interpret the datafile by comparing the file signature with the built-in data reading plugins and any user defined plugins. Specifying a particular product allows the user to override this automatic detection.
cis.read_data
The read_data_list function is very similar to read_data except that it allows the user to specify more than one variable name. This function returns a list of data objects, either all of which will be gridded, or all ungridded, but not a mix. For ungridded data lists it is assumed that all objects share the same coordinates.
cis.read_data_list
Each of the above methods return either ~GriddedData or ~UngriddedData objects. These objects are the main data handling objects used within CIS, and the methods on each of these types are documented in the data modules <cis.data_io_objects> section. These classes do however share a common interface, defined by the CommonData class, which is detailed below. For technical reasons some methods which are common to both ~GriddedData and ~UngriddedData are not defined in the CommonData interface. The most useful of these methods are probably summary and save_data.
cis.data_io.common_data.CommonData
Warning
While the above interfaces are designed as a 'public' API and unlikely to change over CIS versions, those documented below are not yet standardised and may change or be removed even between minor version revisions. It is expected however that these particular classes will be developed and stabilised over time to form part of the 'public' API.
The main collocation class can be imported using from cis.collocation import Collocate, it's methods are outlined below:
cis.collocation.Collocate
The main collocation class can be imported using from cis.aggregation import Aggregate, it's methods are outlined below. Note that currently this object saves the output directly to file, but it is expected that in the future it will return the result for the user to output as needed.
cis.aggregation.Aggregate
The main collocation class can be imported using from cis.subsetting import Subset, it's methods are outlined below: Note that currently this object saves the output directly to file, but it is expected that in the future it will return the result for the user to output as needed.
cis.subsetting.Subset
Fix the plotting interface
The main collocation class can be imported using from cis.stats import StatsAnalyzer, it's methods are outlined below:
cis.stats.StatsAnalyzer
The rest of the documentation below documents internal CIS functions and modules which are not intended to be used as an API at all. They are documented here as a reference for developers and other interested parties.
cis.data_io cis.aggregation cis.collocation cis.plotting cis.subsetting cis_stats cis_utils cis_exceptions