# xgrads
[](https://zenodo.org/badge/latestdoi/244529165)
[](https://xgrads.readthedocs.io/en/latest/?badge=latest)
[](https://badge.fury.io/py/xgrads)
[](https://github.com/miniufo/xgrads/actions/workflows/PyPI-publish.yml)
[](https://github.com/miniufo/xgrads/actions/workflows/tests.yml)
[](https://app.travis-ci.com/miniufo/xgrads)
## 1. Introduction
The Grid Analysis and Display System ([GrADS](http://cola.gmu.edu/grads/) or [OpenGrADS](http://www.opengrads.org/)) is a widely used software for easy access, manipulation, and visualization of earth science data. It uses a [descriptor (or control) file with a suffix `.ctl`](http://cola.gmu.edu/grads/gadoc/descriptorfile.html) to describe a raw binary 4D dataset. The `ctl` file is similar to the header information of a [NetCDF](https://www.unidata.ucar.edu/software/netcdf/docs/file_structure_and_performance.html) file, containing all the information about dimensions, attributes, and variables except for the variable data.
This python package [`xgrads`](https://github.com/miniufo/xgrads) is designed for parse and read the `.ctl` file commonly used by [GrADS](http://cola.gmu.edu/grads/). Right now it can parse various kinds of `.ctl` files. However, only the commonly used raw binary 4D datasets can be read using [`dask`](https://dask.org/) and return as a [`xarray.Dataset`](http://xarray.pydata.org/en/stable/) Other types of binary data, like `dtype` is `station` or`grib`, may be supported in the future.
---
## 2. How to install
**Requirements**
`xgrads` is developed under the environment with `xarray` (=version 0.15.0), `dask` (=version 2.11.0), `numpy` (=version 1.15.4), `cartopy` (=version 0.17.0), and `pyproj` (=version 1.9.6). Older versions of these packages are not well tested.
**Install via pip**
```
pip install xgrads
```
**Install from github**
```
git clone https://github.com/miniufo/xgrads.git
cd xgrads
python setup.py install
```
---
## 3. Examples
### 3.1 Parse a `.ctl` file
Parsing a `.ctl` file is pretty simple using the following code:
```python
from xgrads import CtlDescriptor
ctl = CtlDescriptor(file='test.ctl')
# print all the info in ctl file
print(ctl)
```
If you have already load the ASCII content in the `.ctl` file, you can do it as:
```python
content = \
"dset ^binary.dat\n" \
"* this is a comment line\n" \
"title 10-deg resolution model\n" \
"undef -9.99e8\n" \
"xdef 36 linear 0 10\n" \
"ydef 19 linear -90 10\n" \
"zdef 1 linear 0 1\n" \
"tdef 1 linear 00z01Jan2000 1dy\n" \
"vars 1\n" \
"test 1 99 test variable\n" \
"endvars\n"
ctl = CtlDescriptor(content=content)
# print all the info
print(ctl)
```
---
### 3.2 Read binary data into a `xarray.Dataset`
Reading a `.ctl` related binary data file is also pretty simple using the following code:
```python
from xgrads import open_CtlDataset
dset = open_CtlDataset('test.ctl')
# print all the info in ctl file
print(dset)
```
Then you have the `dset` as a `xarray.Dataset`. This is similar to [`xarray.open_dataset`](http://xarray.pydata.org/en/stable/generated/xarray.open_dataset.html) that use [`dask`](https://dask.org/) to chunk (buffer) parts of the whole dataset in physical memory if the whole dataset is too large to fit in.
If there are many `.ctl` files in a folder, we can also open all of them in a single call of `open_mfdataset` as:
```python
from xgrads import open_mfDataset
dset = open_mfDataset('./folder/*.ctl')
# print all the info in ctl file
print(dset)
```
assuming that every `.ctl` file has similar data structure except the time step is different. This is similar to [`xarray.open_mfdataset`](http://xarray.pydata.org/en/v0.12.3/generated/xarray.open_mfdataset.html).
---
### 3.3 Convert a GrADS dataset to a NetCDF dataset
With the above functionality, it is easy to convert a `.ctl` ([GrADS](http://cola.gmu.edu/grads/)) dataset to a `.nc` ([NetCDF](https://www.unidata.ucar.edu/software/netcdf/docs/file_structure_and_performance.html)) dataset:
```python
from xgrads import open_CtlDataset
open_CtlDataset('input.ctl').to_netcdf('output.nc')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/miniufo/xgrads",
"name": "xgrads",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "grads opengrads xarray dask",
"author": "miniufo",
"author_email": "miniufo@163.com",
"download_url": "https://files.pythonhosted.org/packages/59/d9/6193bb4266d885a571ca7396deb1fc404aa2019a7642087ba56f134c1f39/xgrads-0.2.6.tar.gz",
"platform": null,
"description": "# xgrads\n\n[](https://zenodo.org/badge/latestdoi/244529165)\n\n[](https://xgrads.readthedocs.io/en/latest/?badge=latest)\n[](https://badge.fury.io/py/xgrads)\n[](https://github.com/miniufo/xgrads/actions/workflows/PyPI-publish.yml)\n[](https://github.com/miniufo/xgrads/actions/workflows/tests.yml)\n[](https://app.travis-ci.com/miniufo/xgrads)\n\n\n\n\n## 1. Introduction\nThe Grid Analysis and Display System ([GrADS](http://cola.gmu.edu/grads/) or [OpenGrADS](http://www.opengrads.org/)) is a widely used software for easy access, manipulation, and visualization of earth science data. It uses a [descriptor (or control) file with a suffix `.ctl`](http://cola.gmu.edu/grads/gadoc/descriptorfile.html) to describe a raw binary 4D dataset. The `ctl` file is similar to the header information of a [NetCDF](https://www.unidata.ucar.edu/software/netcdf/docs/file_structure_and_performance.html) file, containing all the information about dimensions, attributes, and variables except for the variable data.\n\nThis python package [`xgrads`](https://github.com/miniufo/xgrads) is designed for parse and read the `.ctl` file commonly used by [GrADS](http://cola.gmu.edu/grads/). Right now it can parse various kinds of `.ctl` files. However, only the commonly used raw binary 4D datasets can be read using [`dask`](https://dask.org/) and return as a [`xarray.Dataset`](http://xarray.pydata.org/en/stable/) Other types of binary data, like `dtype` is `station` or`grib`, may be supported in the future.\n\n---\n## 2. How to install\n**Requirements**\n`xgrads` is developed under the environment with `xarray` (=version 0.15.0), `dask` (=version 2.11.0), `numpy` (=version 1.15.4), `cartopy` (=version 0.17.0), and `pyproj` (=version 1.9.6). Older versions of these packages are not well tested.\n\n**Install via pip**\n```\npip install xgrads\n```\n\n**Install from github**\n```\ngit clone https://github.com/miniufo/xgrads.git\ncd xgrads\npython setup.py install\n```\n\n\n---\n## 3. Examples\n### 3.1 Parse a `.ctl` file\nParsing a `.ctl` file is pretty simple using the following code:\n```python\nfrom xgrads import CtlDescriptor\n\nctl = CtlDescriptor(file='test.ctl')\n\n# print all the info in ctl file\nprint(ctl)\n```\n\nIf you have already load the ASCII content in the `.ctl` file, you can do it as:\n```python\ncontent = \\\n \"dset ^binary.dat\\n\" \\\n \"* this is a comment line\\n\" \\\n \"title 10-deg resolution model\\n\" \\\n \"undef -9.99e8\\n\" \\\n \"xdef 36 linear 0 10\\n\" \\\n \"ydef 19 linear -90 10\\n\" \\\n \"zdef 1 linear 0 1\\n\" \\\n \"tdef 1 linear 00z01Jan2000 1dy\\n\" \\\n \"vars 1\\n\" \\\n \"test 1 99 test variable\\n\" \\\n \"endvars\\n\"\n\nctl = CtlDescriptor(content=content)\n\n# print all the info\nprint(ctl)\n```\n---\n\n### 3.2 Read binary data into a `xarray.Dataset`\nReading a `.ctl` related binary data file is also pretty simple using the following code:\n```python\nfrom xgrads import open_CtlDataset\n\ndset = open_CtlDataset('test.ctl')\n\n# print all the info in ctl file\nprint(dset)\n```\n\nThen you have the `dset` as a `xarray.Dataset`. This is similar to [`xarray.open_dataset`](http://xarray.pydata.org/en/stable/generated/xarray.open_dataset.html) that use [`dask`](https://dask.org/) to chunk (buffer) parts of the whole dataset in physical memory if the whole dataset is too large to fit in.\n\nIf there are many `.ctl` files in a folder, we can also open all of them in a single call of `open_mfdataset` as:\n```python\nfrom xgrads import open_mfDataset\n\ndset = open_mfDataset('./folder/*.ctl')\n\n# print all the info in ctl file\nprint(dset)\n```\nassuming that every `.ctl` file has similar data structure except the time step is different. This is similar to [`xarray.open_mfdataset`](http://xarray.pydata.org/en/v0.12.3/generated/xarray.open_mfdataset.html).\n\n---\n\n### 3.3 Convert a GrADS dataset to a NetCDF dataset\nWith the above functionality, it is easy to convert a `.ctl` ([GrADS](http://cola.gmu.edu/grads/)) dataset to a `.nc` ([NetCDF](https://www.unidata.ucar.edu/software/netcdf/docs/file_structure_and_performance.html)) dataset:\n```python\nfrom xgrads import open_CtlDataset\n\nopen_CtlDataset('input.ctl').to_netcdf('output.nc')\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parse and read ctl file commonly used by GrADS.",
"version": "0.2.6",
"project_urls": {
"Homepage": "https://github.com/miniufo/xgrads"
},
"split_keywords": [
"grads",
"opengrads",
"xarray",
"dask"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "34107ad041840cc200e7fd9c96ef660e4d0a21c092e5325809726bb247046a91",
"md5": "b538e7ce98addb7c3fd1131fb57f78c3",
"sha256": "3e7dbef1a1ae64efd9963164371d839f014277a3261aa44cdfb56f67af829646"
},
"downloads": -1,
"filename": "xgrads-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b538e7ce98addb7c3fd1131fb57f78c3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22465,
"upload_time": "2023-08-06T19:11:34",
"upload_time_iso_8601": "2023-08-06T19:11:34.562287Z",
"url": "https://files.pythonhosted.org/packages/34/10/7ad041840cc200e7fd9c96ef660e4d0a21c092e5325809726bb247046a91/xgrads-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "59d96193bb4266d885a571ca7396deb1fc404aa2019a7642087ba56f134c1f39",
"md5": "b04bc32c61038b59f3ab7461eea4d0e9",
"sha256": "d354bd5c69fbd05bcbbd34ac15d589a6592305dfd1769addd4a0cfeba04d4d97"
},
"downloads": -1,
"filename": "xgrads-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "b04bc32c61038b59f3ab7461eea4d0e9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25397,
"upload_time": "2023-08-06T19:11:36",
"upload_time_iso_8601": "2023-08-06T19:11:36.051542Z",
"url": "https://files.pythonhosted.org/packages/59/d9/6193bb4266d885a571ca7396deb1fc404aa2019a7642087ba56f134c1f39/xgrads-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-06 19:11:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "miniufo",
"github_project": "xgrads",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "xgrads"
}
JSON
