Skip to content

Commit

Permalink
Merge pull request #68 from mx-moth/docs
Browse files Browse the repository at this point in the history 
Update documentation
  • Loading branch information
@mx-moth
mx-moth authored Feb 28, 2023
2 parents 7969744 + fbc4244 commit d20870f
Show file tree
Hide file tree
Showing 5 changed files with 159 additions and 371 deletions.
13 changes: 13 additions & 0 deletions .readthedocs.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
version: 2

build:
os: ubuntu-22.04
tools:
python: "3.11"

python:
install:
- requirements: docs/requirements.txt

mkdocs:
configuration: mkdocs.yml
260 changes: 11 additions & 249 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,14 @@

Python bindings for [NCO](http://nco.sourceforge.net/). A fork from Ralf Mueller's [cdo-bindings](https://github.com/Try2Code/cdo-bindings).

## `pynco` - Use Python to access the power of [NCO](http://nco.sourceforge.net/)

This package contains the module python `nco`, which implements a python style access to the [NetCDF Operators (NCO)](http://nco.sourceforge.net/). NCO is a command line tool for processing netCDF data. Its main focus is climate data, but it can by used for other purposes too.


## Documentation

Read the documentation at [pynco.readthedocs.org](https://pynco.readthedocs.io/)


## Installation

### Conda Installation (recommended)
Expand All @@ -19,271 +22,30 @@ conda install -c conda-forge pynco

### PyPI Installation

Please see [the requirements](#requirements) before installing
Please see [the requirements](https://pynco.readthedocs.org/en/latest/#requirements) before installing

```bash
pip install nco
```

### Python Installation

Please see [the requirements](#requirements) before installing

```bash
python setup.py install
```


### Requirements

**Mandatory**

- ***Platform***: Unix or Mac OS (Windows has not bee tested)
- [NetCDF Operators (NCO)](http://nco.sourceforge.net/) - Version 4.6.9 or later. We don't test against every NCO version.
- Python 3.6 or 3.7

**Recommended**

These will allow `pynco` operations to return `numpy` arrays

- [scipy](http://docs.scipy.org/doc/scipy/reference/generated/scipy.io.netcdf.netcdf_file.html)
- [netCDF-4](https://code.google.com/p/netcdf4-python/)
- [numpy](http://www.numpy.org/)


## Usage

#### Importing the Nco class

```python
from nco import Nco
```

### Run operators

For python an instance has to be created first
## Example

```python
from nco import Nco
nco = Nco()
temperatures = nco.ncra(input='input.nc', returnCdf=True).variables['T'][:]
```

Now any NCO command (i.e. `ncks`, `ncra`, ...) can be called as a method of `nco`.

* Required arguments
- `input` - Input netcdf file name, str

* Optional arguments

- `output` - `str` or `list` of strings representing input netCDF filenames. If not provided and operator returns a file (not an array or stdout text), the method will return a temporary file.
- `debug` - `bool` or `int`, if less than 0 or True, debug statements will be turned on for NCO and NCOpy (default: `False`)
- `returnCdf` - `bool`, return a netCDF file handle (default: `False`)
- `returnArray` - `str`. return a numpy array of variable name (default: `''`)
- `returnMaArray` - `str`. return a numpy masked array of variable name (default: `''`)
- `options` - `list`, NCO input options, for example `options=['-7', '-L 1']` (default: `[]`)
- `Atted` - a wrapper object to be used for ncatted. Atted objects can be included in the options list
- `Limit` - a wrapper object for the hyperslab (`-d`) command line option
- `Rename` - a wrapper object for the `-d`, `-a`, `-v`, and `-g` command line options in `ncrename`
- `**kwargs` - any kwarg will be passed as a key, value pair to the nco command `--{key}={value}`. This allows the user to pass any number of long name commands list in the nco help pages.


### Examples

* File information:

## Support, issues, bugs, ...

* Operators with user defined regular output files:

```python
nco.ncra(input=ifile, output=ofile)
```

* Use temporary output files:

```python
temp_ofile = nco.ncrcat(input=ifile)
```

* Set global NCO options:

```python
nco.ncks(input=ifile, output=ofile, options="--netcdf4")
```

* Return multi-dimension arrays:

```python
temperatures = nco.ncra(input=ifile, returnArray=True).variables['T'][:]
temperatures = nco.ncra(input=ifile, returnCdf=True).variables['T'][:]
temperatures = nco.ncra(input=ifile, returnArray='T')
```

* Wrapper Objects

Three convenient wrapper objects can be imported from `nco.custom`.

- The `Atted` object is a convienent wrapper object to the `-a` command-line switch in ncatted.
- The `Limit` object is a wrapper to the `-d` command-line switch.
- The `Rename` is a wrapper for the `-a, -v, -d , -g ` switches in ncrename.

For example, the following are equivalent:

```
nco.ncatted(input="in.nc",options=[Atted("overwrite","_FillValue","three_dmn",-9.91e+33,'d')])
ncatted -a _FillValue,three_dmn,o,d,-9.91e+33 in.nc
```

## Tempfile helpers

`pynco` includes a simple tempfile wrapper, which makes life easier. In the
absence of a specified output file, `pynco` will create a temporary file to allow the results of the task to be returned to the user. For example:

```python
temperatures = nco.ncra(input=ifile, returnArray='T')
```

is equivalent to:

```
temperatures = nco.ncra(input=ifile, output=tempfile.mktemp(), returnArray='T')
```


## Atted wrapper

It is sometimes more tidy to define the atted objects in a separate list then add that list the options in the nco call

```python
from nco import Nco
from nco.custom import Atted
nco = Nco()
opt = [
Atted("o", "units", "temperature", "Kelvin"),
Atted("c", "min", "temperature", 0.16, 'd'),
Atted("m", "max", "temperature", 283.01, 'float64'),
Atted("c", "bnds", "time", [0.5, 1.5], 'f')
]
nco.ncatted(input="in.nc", options=opt)
```

You can also use keyword arguments in the call so the above options become

```python
from nco import Nco
from nco.custom import Atted
nco = Nco()
opt = [
Atted(mode="o", attName="units", varName="temperature", Value="Kelvin", sType="c"),
Atted(mode="create", attName="min", varName="temperature", Value=0.16, sType='d' ),
Atted(mode="modify", attName="max", varName="temperature", Value=283.01, sType='float64'),
Atted(mode="create", attName="bnds", varName="time", Value=[0.5, 1.5], sType='float32')
]
nco.ncatted(input="in.nc", options=opt)
```

#### `Value`

Can be a single value or a list (or any python iterable type or a numpy array).

* If sType **is not** included then the type is inferred from the first value in the list
* If sType **is** included then any values in the list are **not** of sType are converted to the sType

#### `sType`

You can use the following: `f, d, l/i, s, b, ub, us, u, ll, ull`
Or their numpy equivalents: `float32, float64, int32, int16, byte, ubyte, uint16, uint32, int64, uint64`

For a netCDF3 character string use `c` or `char`
For netCDF4 string(s) use `sng` or `string`

#### `mode`

For mode you can use the single character abbreviations as per `ncatted`: `a, c, d, m, n, o` or the following words: `a)ppend, create, delete, modify, overwrite`


## Limit and LimitSingle wrapper

The following are equivalent:

**nco**

```bash
ncks -d time,0,8,2 -d time,10 -d lat,-20.0,20.0 -d lon,50.0,350.0 -d lev,,,4
```

**pynco**

```python
from nco import Nco
from nco.custom import Limit
nco = Nco()
opt = [
Limit("time", 0, 8, 2),
LimitSingle("time", 10),
Limit("lat", -20.0, 20.0),
Limit(dmn_name="lon", srt=50.0, end=350.0),
Limit(dmn_name="lev", srd=4)
]

nco.ncks(input="in.nc", output="out.nc", options=opt)
```

## Rename wrapper

The following are equivalent:

**`nco`**

```bash
ncrename -v p,pressure -v t,temperature in.nc
```

**`pynco`**

```python
from nco import Nco
from nco.custom import Rename
nco = Nco()
rDict = {
'p': 'pressure',
't': 'temperature'
}
nco.ncrename(input="in.nc", options=[ Rename("variable", rDict) ])
```

Also equivalent:

**`nco`**

```bash
ncrename -d lon,longitude -d lat,latitude -v lon,longitude -v lat,latitude in.nc
```

**`pynco`**

```python
from nco import Nco
from nco.custom import Rename
rDict = {
'lon': 'longitude',
'lat': 'latitude'
}
nco.ncrename(input="in.nc", options=[ Rename("d", rDict), Rename("v", rDict) ])
```

## Support, Issues, Bugs, ...

Please use the github page to report issues/bugs/features: https://github.com/nco/pynco.
Please use the github page to report issues, bugs, and features:
https://github.com/nco/pynco.

For usage questions, please use [Stack Overflow](https://stackoverflow.com/questions/tagged/nco).


## License

`pynco` makes use of the MIT License, see LICENSE.txt.


## Other stuff

* Requires: NCO version 4.6.9 or newer, Python 3.6 or later
* Optional: scipy or Python netCDF4
Loading

0 comments on commit d20870f

Please sign in to comment.