From 2305c62415d8d2fee7331278232db4bfaa328d62 Mon Sep 17 00:00:00 2001 From: Denis Nadeau Date: Wed, 10 Apr 2019 14:16:07 -0700 Subject: [PATCH] Docstanya (#318) * Some changes to Regrid 2, Lib, esmf, gsRegrid and horizontal * Changes made to Chapters 1-7 and sample data * fix API documentation * rename regrid2 directory and delete print message * add module API files * add future and mock requirements * get cwd for readthedocs * Changes made to API * Changes made to API * Changes made to API * Changes to API * test rtd with mock * add future for readthedocs * create git.py in ../.. * add esmf * add print statements for regrid2 * add print for libregrid2 * restore regrid2.Lib for readthedocs * add mock modules * add git.py * try with new mock list * force git.py * force git.py * try readthedocs.yml file * fix readthedocs maping file * change type pdb to pdf * typo requirements.yml * add dependencies * add dependencies and change conf.yml * change API.rst and other rst files * Changes to API * UVCDAT_ANONYMOUS_LOG set to false * check if git.py is there * add gcc to environment.yml * try docker environment.yml * remove git.py * chage Libregrid to regrid2 * revert * revert * add cdms2 class * delet cdms2 class * delet cdms2 class * change conf.py os.path * Changes to API * Changes made to API * Changes to API * Changes made to API * Changes to API * Changes made to API * Changes made to API * Changes to API * Changes to API * Changes made to API * Changes made to API * Changes made to API * push latest rst files * Changes made to API * Made some changes to API * update documentations * Changes made to API * Changes made to API * Changes made to API * Changes made to Section 2 and API * Changes made to Section 2 * Changes made to Chapter 2 * Changes made to Section 2 * Changes made to Chapters 2, 3, 4,5 and 6 * Changes made to Sections 2, 4, 7 and Appendix * Changes made to Chapter 6 and Appendix * Changes made to Section 2 * update summary table for API * add generated files * Changes made to al sections * Changes made to Section 2 and API * Changes made to 2 and API * Made changes to sections 1 and 2 * Issue#231 (#232) * fix #225 passing transiant variable as axis * Fix macOSX * fix ESMF and NPY_STRING * fix data._mask comparison for numpy 1.14 * failing test from vcs added here (#234) * failing test from vcs added here * ok test passes again * reverted for now * commented out test for @durack1 * Cdmsdocsmerge (#223) * First cdms2 documentation revamp * latest changes * add new files and work on avariable documentations * fix index order * revamp documentation * Fixing cdms documentation (docstrings) * update documentation * continue to work on docs * sphinx doctest in manual.rst * chapter 1 continu * add requirments.txt for read-the-doc * move requirements.txt into docs dir * add requirements * Chapter 2 * add chapter 3 * finish chapter 3 started chapter 4 * flake8 python files * chapter 4 regridding * cdms_4 doctest * add other chapters * finish chapter 4 * add chapter 5 * add chapter 6 * cdms chapter 6 * fix TOC * add chapter 7 and appendix * merge docs * add requirements.txt * remove cdat_info * remote cdat_info * fix latex_logo png * pin pyopenssl to 17.2.0 due to myproxyclient failure in py3 * update TOC * work on tables and setup * try to force jquery 3.1 * just copy js script in _static * add highlight python * add sample dataset page * add sample dataset page * work on tables for cdms_2.rst * continue cdms2 documentations * update cdms2 tables * update sections * update table * finish chapter 2 * fix litteral error * unlink .dodsrc for cdscan * First changes from Tanya * some change in chapter 1 and 2 * some changes in Chapter 2 * fix tables * Some changes to Chapter 2 * Some Changes to Chapter 2 * Some changes made to Chapters 1, 2 and 4 * Some changes to Chapter 2 * Some Changes made to Chapter 2 * Some changes to Chapters 2, 3 and 4 * Some changes made to 1 through Appendix * Some Changes made to Chapter 2 * Some Changes to Chapters 1, 2, 3, 6 and Appendix * Some changes made to Chapters 1 thru 7 and appendix * Some changes to Chpaters 1, 2 and 3 * Changes made to Chapters 1, 4, 5 and Appendix * Some changes to Chapter 2 and 4 * Some Changes to Images, Chapter 3 and Appendix * update logo * add my logo * fix chapter 1 test * Fix python3 slice issue(setitem) and flake8 (#243) * fix python 3 aggregation issue and flake8 (#244) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * Netcdf46 (#249) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * try circleci unstable label * try version 2 circleci * try version 2 circleci * change workflow name * change cdtime to cdms * add certificate to circleci * add fix conda-upload in circleci 2.0 * update prep_for_build version * fix curl command * fix cicleci for cdms * use unstable channel change uvcdat for cdat * build cdms on circleci 2.0 * fix circleci config.yml * change Users/distiler to /Users/denisnadeau * add gcc_linux * add LDSHARED for linux * disable cert and py results * add gcc_linux-64 * change cdscan link * fix myproxy * add esmf and esmpy to py3 env * Revert "Netcdf46 (#249)" (#250) This reverts commit a9e29eaaecd1158071660d4ce26ccafb56820639. * Netcdf46 (#251) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * try circleci unstable label * try version 2 circleci * try version 2 circleci * change workflow name * change cdtime to cdms * add certificate to circleci * add fix conda-upload in circleci 2.0 * update prep_for_build version * fix curl command * fix cicleci for cdms * use unstable channel change uvcdat for cdat * build cdms on circleci 2.0 * fix circleci config.yml * change Users/distiler to /Users/denisnadeau * add gcc_linux * add LDSHARED for linux * disable cert and py results * add gcc_linux-64 * change cdscan link * fix myproxy * add esmf and esmpy to py3 env * inverse dodsrc and curl commands * move unlink above cdscan test * fix ESGF test * add new dodsrc files * create dodsrc on-demand * put back tests for unstable * Netcdf46 (#252) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * try circleci unstable label * try version 2 circleci * try version 2 circleci * change workflow name * change cdtime to cdms * add certificate to circleci * add fix conda-upload in circleci 2.0 * update prep_for_build version * fix curl command * fix cicleci for cdms * use unstable channel change uvcdat for cdat * build cdms on circleci 2.0 * fix circleci config.yml * change Users/distiler to /Users/denisnadeau * add gcc_linux * add LDSHARED for linux * disable cert and py results * add gcc_linux-64 * change cdscan link * fix myproxy * add esmf and esmpy to py3 env * inverse dodsrc and curl commands * move unlink above cdscan test * fix ESGF test * add new dodsrc files * create dodsrc on-demand * put back tests for unstable * instal anaconda-client before calling conda-upload * Changes made to API * Made some changes to API * Changes made to API * Changes made to API * Changes made to API * Changes made to Section 2 and API * Changes made to Section 2 * Changes made to Chapter 2 * Changes made to Section 2 * Changes made to Chapters 2, 3, 4,5 and 6 * Changes made to Sections 2, 4, 7 and Appendix * Changes made to Chapter 6 and Appendix * Changes made to Section 2 * Changes made to al sections * Changes made to Section 2 and API * Changes made to 2 and API * Made changes to sections 1 and 2 * Issue#231 (#232) * fix #225 passing transiant variable as axis * Fix macOSX * fix ESMF and NPY_STRING * fix data._mask comparison for numpy 1.14 * Fix python3 slice issue(setitem) and flake8 (#243) * fix python 3 aggregation issue and flake8 (#244) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * Netcdf46 (#249) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * try circleci unstable label * try version 2 circleci * try version 2 circleci * change workflow name * change cdtime to cdms * add certificate to circleci * add fix conda-upload in circleci 2.0 * update prep_for_build version * fix curl command * fix cicleci for cdms * use unstable channel change uvcdat for cdat * build cdms on circleci 2.0 * fix circleci config.yml * change Users/distiler to /Users/denisnadeau * add gcc_linux * add LDSHARED for linux * disable cert and py results * add gcc_linux-64 * change cdscan link * fix myproxy * add esmf and esmpy to py3 env * Revert "Netcdf46 (#249)" (#250) This reverts commit a9e29eaaecd1158071660d4ce26ccafb56820639. * Netcdf46 (#251) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * try circleci unstable label * try version 2 circleci * try version 2 circleci * change workflow name * change cdtime to cdms * add certificate to circleci * add fix conda-upload in circleci 2.0 * update prep_for_build version * fix curl command * fix cicleci for cdms * use unstable channel change uvcdat for cdat * build cdms on circleci 2.0 * fix circleci config.yml * change Users/distiler to /Users/denisnadeau * add gcc_linux * add LDSHARED for linux * disable cert and py results * add gcc_linux-64 * change cdscan link * fix myproxy * add esmf and esmpy to py3 env * inverse dodsrc and curl commands * move unlink above cdscan test * fix ESGF test * add new dodsrc files * create dodsrc on-demand * put back tests for unstable * Netcdf46 (#252) * Fix python3 slice issue(setitem) and flake8 * update to libnetcdf 4.6 * try circleci unstable label * try version 2 circleci * try version 2 circleci * change workflow name * change cdtime to cdms * add certificate to circleci * add fix conda-upload in circleci 2.0 * update prep_for_build version * fix curl command * fix cicleci for cdms * use unstable channel change uvcdat for cdat * build cdms on circleci 2.0 * fix circleci config.yml * change Users/distiler to /Users/denisnadeau * add gcc_linux * add LDSHARED for linux * disable cert and py results * add gcc_linux-64 * change cdscan link * fix myproxy * add esmf and esmpy to py3 env * inverse dodsrc and curl commands * move unlink above cdscan test * fix ESGF test * add new dodsrc files * create dodsrc on-demand * put back tests for unstable * instal anaconda-client before calling conda-upload * Fix table titles * Change made to Section 4 * fix bindex issue in hgrid * Changes to all * Corrections made to API Lib * Changes to API * fix ascii art * Changes to Sections 2, 4 and 5 * Changes made to all * Changes made to Sections 2, 6 and Appendix * Changes made to Section 2 * Changes made to Section 2 * Changes made to Section 2 and 5 * Changes to Sections 2, 6 and 7 * Changes to API * Changes made to API * Made Changes to API * Changes made to API * Changes made to Section 4 and 7 * Changes made to API * Changes made to API * Revisit run tests (#262) * migrate run_tests.py to use TestRunnerBase * remove accidentally added tests/coverage.json * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * revisit run_tests.py * add cacert.pem in run_tests.py when running cdms test within the lab * add cacert.pem in run_tests.py when running cdms test within the lab * add cacert.pem in run_tests.py when running cdms test within the lab * add cacert.pem in run_tests.py when running cdms test within the lab - rerun tests * add cacert.pem in run_tests.py when running cdms test within the lab - remove install from -c cdat/label/unstable * put back -c cdat/label/unstable * fix Axis.py * update documentation * fix environment dependencies * add/remote generated files * try to fix API.rst * add regrid2 to docs * Changes made to API * fix space with parameters * fix readthedocs using numpydoc * update environment * fix some autodocs * add hgrid * Changes made to API * Changes made to API * fix avariable bad location methods * Changes to Appendix and API * Changes to Chapter 1 and 2 * Changes made to Section 2 * Changes made to Section 2 * Changes made to Section 2 * Changes to sections 1, 2, 3 and 4 * Changes to section 2 * Changes made to entire docuemnt * Changes to Section 1 and 2 * Changes made to Section 2 * Changes made to Sections 2 thru 6 * Changes made to Chapters 3 and 6 * add jupyter notebook * Changes to all * Changes to Jupyter Notebooks * Changes to all * update documentation for version 3.1.0 * merge documentations * change banner and sidebar colors * Changes to API * fix style sheet * Changes to API * Changes to API * Changes to API and Sections * Changes to all * will this fix master? (#292) * Changes to Sections 1 and 2 * fix cdtime and scripts * trigger read-the-docs * fix more cdtime doc issues * fix typo Default-Calendar * fix conflicts * pass flake8 * udpate chapter1 * Changes * add jupyter notebook * jupyter chapter1 fixed * cleanup chapter 1 jupyter * add tmp_T42_to_POP43_conserv file * chapter 2 and chapter 3 * Changes to Jupyter Notebooks 1 and 2 * clean up * update chapter4 * chapter 4 regridder opendap * chapter 2 using OpenDAP * chapter 2 using OpenDAP * update all chapters * add chapter4 * Changes to Jupiter Notebooks 1 and 2 * Changes to Jupyter Notebooks 1a and 2a * Changes to Jupyter Notebooks 1a, 2a, 3a, 4a * Changes to Jupyter Notebooks 1a, 2a, 3a,4a, 5a * Changes to Jupyter Notebooks 1a thru 4a * Changes to Section 1, 2 * Changes to Sections 1 and 2 * Changes to Sections 1-3 * Changes to Jupyter Notebooks * Changes to Chapters 2, 5 and 6 * Changes to Sections 1 and 2 * Changes to API * fix double Notes section * Changes to API * Changes made to API * Change to API * Changes to API * Changes to API * Changes to Sections * Changes to Sections * Changes to Section 1 * Changes to all * Changes to Sections 2 and 4 * flake8 files * Changes to sections * update readthedocs to py3 * update environment.yml to 3.1.2 * fix environment.yml for readthedocs * add easydev to readthedocs env yaml * change sys.prefix to 3.7 * try to add lazy-object and change env * enable javascript button --- docs/source/manual/cdms_1.rst | 244 +++--- docs/source/manual/cdms_2.rst | 1106 ++++++++------------------ docs/source/manual/cdms_3.rst | 116 +-- docs/source/manual/cdms_4.rst | 58 +- docs/source/manual/cdms_5.rst | 82 +- docs/source/manual/cdms_6.rst | 156 ++-- docs/source/manual/cdms_7.rst | 70 +- docs/source/manual/cdms_appendix.rst | 74 +- docs/source/manual/sample_data.rst | 8 + 9 files changed, 733 insertions(+), 1181 deletions(-) diff --git a/docs/source/manual/cdms_1.rst b/docs/source/manual/cdms_1.rst index 4af6cb15..0c6974d2 100644 --- a/docs/source/manual/cdms_1.rst +++ b/docs/source/manual/cdms_1.rst @@ -4,9 +4,12 @@ Introduction Overview ^^^^^^^^ +.. highlight:: python + + The Community Data Management System is an object-oriented data management system, specialized for organizing multidimensional, gridded data used -in climate analysis and simulation. +in climate analysis and simulation. CDMS is implemented as part of the Climate Data Analysis Tool (CDAT), which uses the Python language. The examples in @@ -28,17 +31,13 @@ the eastward and northward components of wind speed, respectively, and both variables are functions of time, latitude, and longitude, then the velocity for time 0 (first index) can be calculated as: - -.. highlight:: python - -.. +:: >>> # wget "http://cdat.llnl.gov/cdat/sample_data/clt.nc" >>> f1=cdms2.open("clt.nc") >>> u = f1('u') >>> v = f1('v') >>> from cdms2 import MV - >>> vel = MV.sqrt(u[0]**2 + v[0]**2) This illustrates several points: @@ -62,14 +61,14 @@ File I/O ^^^^^^^^ A variable can be obtained from a file or collection of files, or can be -generated as the result of a computation. +generated as the result of a computation. Files can be in any of theself- describing formats: netCDF, HDF, GrADS/GRIB (GRIB with a GrADS control file), or PCMDI DRS. -**Note:** (HDF and DRS support is optional, and is configured at the time CDAT is installed.) +**Note:** (HDF and DRS support is optional, and is configured at the time CDAT is installed.) For instance, to read datafrom file sample.nc into variable u: @@ -83,7 +82,7 @@ For instance, to read datafrom file sample.nc into variable u: f2 = cdms2.open(cdat_info.get_sampledata_path()+'/geos5-sample.nc') u = f('u') v = f('v') - smallvar=MV2.reshape(MV2.arange(20),(4,5),id='small variable').astype(MV2.float32) + smallvar=MV2.reshape(MV2.arange(20),(4,5),id='small variable').astype(MV2.float32) largevar=MV2.reshape(MV2.arange(400),(20,20),id="large variable").astype(MV2.float32) fnames = [ 'clt.nc', 'geos-sample', 'xieArkin-T42.nc', 'remap_grid_POP43.nc', 'remap_grid_T42.nc', 'rmp_POP43_to_T42_conserv.n', 'rmp_T42_to_POP43_conserv.nc', 'ta_ncep_87-6-88-4.nc', 'rmp_T42_to_C02562_conserv.nc' ] for file in fnames: @@ -99,7 +98,7 @@ For instance, to read datafrom file sample.nc into variable u: os.remove(file) -.. +:: >>> # wget "http://cdat.llnl.gov/cdat/sample_data/clt.nc" >>> f = cdms2.open('clt.nc') @@ -109,20 +108,20 @@ Data can be read by index or by world coordinate values. The following reads the n-th timepoint of u (the syntax slice(i,j) refers to indices k such that i <= k < j): -.. +:: >>> n = 0 >>> u0 = f('u',time=slice(n,n+1)) To read ``u`` at time 1.: -.. +:: >>> u1 = f('u',time=1.) A variable can be written to a file with the write function: -.. +:: >>> g = cdms2.open('sample2.nc','w') >>> g.write(u) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE @@ -150,7 +149,7 @@ latitude, longitude). This indicates the order of the dimensions, with the slowest-varying dimension listed first (time). The domain may be accessed with the ``getAxisList()`` method: -.. +:: >>> u.getAxisList() # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE [ id: time1 @@ -214,7 +213,7 @@ associated with a variable. The methods getLatitude, getLongitude, getLevel, and getTime return the associated coordinate axes. For example: -.. +:: >>> t = u.getTime() >>> print t[:] @@ -229,10 +228,10 @@ As mentioned above, variables can have associated attributes , name-value pairs. In fact, nearly all CDMS objects can have associated attributes, which are accessed using the Python dot notation: -.. +:: >>> u.units='m/s' - >>> print u.units + >>> print u.units m/s Attribute values can be strings, scalars, or 1-D Numpy arrays. @@ -245,14 +244,14 @@ written to an output file along with the variable. By default, when an attribute is set, it is treated as external. Every variable has a field attributes, a Python dictionary that defines the external attributes: -.. +:: >>> print u.attributes.keys() 'name', 'title', 'tileIndex', 'date', 'source', 'time', 'units', 'type'] The Python dir command lists the internal attribute names: -.. +:: >>> dir(u) ['T', '_FillValue', '_TransientVariable__domain', ..., 'view'] @@ -272,17 +271,17 @@ corresponding data array element is missing or invalid. Arithmetic operations in CDMS take missing data into account. The same is true of the functions defined in the cdms2.MV2 module. For example: -.. +:: >>> a = MV2.array([1,2,3]) # Create array a, with no mask - >>> b = MV2.array([4,5,6]) # Same for b + >>> b = MV2.array([4,5,6]) # Same for b >>> a+b # variable_... array([5,7,9,]) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE variable_... masked_array(data = [5 7 9], mask = False, - fill_value = 999999) - >>> - >>> + fill_value = 999999) + >>> + >>> >>> a[1]=MV2.masked # Mask the second value of a a.mask() >>> a.mask array([False, True, False], dtype=bool) @@ -291,8 +290,8 @@ is true of the functions defined in the cdms2.MV2 module. For example: masked_array(data = [5 -- 9], mask = [False True False], fill_value = 999999) - - + + When data is read from a file, the result variable is masked if the file variable has a missing_value attribute. The mask is set to one for those elements equal to the missing value, zero elsewhere. If no such @@ -334,10 +333,10 @@ function. **Note** That obtaining a file variable does not actually read the data array: -.. +:: >>> u = f.getVariable('u') # or u=f['u'] - >>> u.shape + >>> u.shape (1, 2, 80, 97) File variables are also useful for fine-grained I/O. They behave like @@ -351,8 +350,8 @@ file. Specifically: - and calling a file variable like a function reads data associated with the variable: -.. - +:: + >>> import os >>> os.system("cp clt.nc /tmp") 0 @@ -360,7 +359,7 @@ file. Specifically: >>> uvar = f['u'] # Note square brackets >>> uvar.shape (1, 2, 80, 97) - >>> u0 = uvar[0] # Reads data from sample.nc + >>> u0 = uvar[0] # Reads data from sample.nc >>> u0.shape (2, 80, 97) >>> uvar[1]=u0 # Writes data to sample.nc @@ -374,24 +373,23 @@ For transient variables, the data is printed only if the size of the array is le than the print limit . This value can be set with the function MV.set_print_limit to force the data to be printed: -.. - +:: >>> MV2.get_print_limit() # Current limit 1000 1000 >>> smallvar # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE - small variable - masked_array(data = + small variable + masked_array(data = [[ 0. 1. 2. 3. 4.] [ 5. 6. 7. 8. 9.] [ 10. 11. 12. 13. 14.] [ 15. 16. 17. 18. 19.]], - mask = + mask = False, fill_value = 999999.0) - >>> MV2.set_print_limit(100) + >>> MV2.set_print_limit(100) >>> largevar # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE - large variable + large variable masked_array(data = [[ 0. 1. 2. ..., 17. 18. 19.] [ 20. 21. 22. ..., 37. 38. 39.] @@ -405,10 +403,9 @@ MV.set_print_limit to force the data to be printed: The datatype of the variable is determined with the typecode function: -.. - +:: - >>> u.typecode() + >>> u.typecode() 'f' Dataset Variables @@ -437,7 +434,7 @@ A metafile can be generated with the command: The metafile **cdsample.xml** is then used like an ordinary data file: -.. +:: >>> import os >>> os.system("cdscan -x cdsample.xml [uv]*.nc") @@ -448,7 +445,7 @@ The metafile **cdsample.xml** is then used like an ordinary data file: (3, 16, 32) Grids -^^^^^^^^ +^^^^^ A latitude-longitude grid represents the coordinate information associated with a variable. A grid encapsulates: @@ -490,65 +487,56 @@ grid. Note that: lon ), each a two-dimensional coordinate axis. - lat and lon each have domain ( y , x ) -.. + +:: >>> f = cdms2.open('sampleCurveGrid4.nc') - >>> - >>> >>> # lat and lon are coordinate axes, but are grouped with data variables - >>> f.variables.keys() - ['lat', 'sample', 'bounds_lon', 'lon', 'bounds_lat'] - >>> + >>> f.variables.keys() + ['lat', 'sample', 'bounds_lon', 'lon', 'bounds_lat'] >>> # y and x are index coordinate axes - >>> f.axes.keys() - ['nvert', 'x', 'y'] - >>> + >>> f.axes.keys() + ['nvert', 'x', 'y'] >>> # Read data for variable sample >>> sample = f('sample') - >>> >>> # The associated grid g is curvilinear >>> g = sample.getGrid() - >>> >>> # The domain of the variable consists of index axes - >>> sample.getAxisIds() + >>> sample.getAxisIds() ['y', 'x'] - >>> >>> # Get the coordinate axes associated with the grid >>> lat = g.getLatitude() # or sample.getLatitude() >>> lon = g.getLongitude() # or sample.getLongitude() - >>> >>> # lat and lon have the same domain, a subset of the domain of 'sample' - >>> lat.getAxisIds() + >>> lat.getAxisIds() ['y', 'x'] - >>> >>> # lat and lon are variables ... - >>> lat.shape - (32, 48) - >>> + >>> lat.shape + (32, 48) >>> lat # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE - lat - masked_array(data = - [[-76.08465554 -76.08465554 -76.08465554 ..., -76.08465554 -76.08465554 - -76.08465554] - [-73.92641847 -73.92641847 -73.92641847 ..., -73.92641847 -73.92641847 - -73.92641847] - [-71.44420823 -71.44420823 -71.44420823 ..., -71.44420823 -71.44420823 - -71.44420823] - ..., - [ 42.32854943 42.6582209 43.31990211 ..., 43.3199019 42.65822088 - 42.32854943] - [ 42.70106429 43.05731498 43.76927818 ..., 43.76927796 43.05731495 - 42.70106429] - [ 43.0307341 43.41264383 44.17234165 ..., 44.17234141 43.41264379 - 43.0307341 ]], - mask = - False, - fill_value = 1e+20) - >>> + lat + masked_array(data = + [[-76.08465554 -76.08465554 -76.08465554 ..., -76.08465554 -76.08465554 + -76.08465554] + [-73.92641847 -73.92641847 -73.92641847 ..., -73.92641847 -73.92641847 + -73.92641847] + [-71.44420823 -71.44420823 -71.44420823 ..., -71.44420823 -71.44420823 + -71.44420823] + ..., + [ 42.32854943 42.6582209 43.31990211 ..., 43.3199019 42.65822088 + 42.32854943] + [ 42.70106429 43.05731498 43.76927818 ..., 43.76927796 43.05731495 + 42.70106429] + [ 43.0307341 43.41264383 44.17234165 ..., 44.17234141 43.41264379 + 43.0307341 ]], + mask = False, fill_value = 1e+20) >>> lat_in_radians = lat*MV2.pi/180.0 - .. figure:: images/curvilinear_grid.jpg + + + +.. figure:: images/curvilinear_grid.jpg :alt: curvilinear grid Figure 1: Curvilinear Grid @@ -561,11 +549,11 @@ Example: A Generic Grid In this example variable zs is defined on a generic grid. Figure 2 illustrates the grid, in this case a geodesic grid: -.. +:: >>> f.variables.keys() ['lat', 'sample', 'bounds_lon', 'lon', 'bounds_lat'] - >>> f.axes.keys() + >>> f.axes.keys() ['nvert', 'x', 'y'] >>> zs = f('sample') >>> g = zs.getGrid() @@ -573,27 +561,25 @@ illustrates the grid, in this case a geodesic grid: >>> lat = g.getLatitude() >>> lon = g.getLongitude() - >>> lat.shape + >>> lat.shape (32, 48) >>> lon.shape # variable zs is defined in terms of a single index coordinate - (32, 48) + (32, 48) >>> # axis, 'cell' - >>> zs.shape - (32, 48) - >>> zs.getAxisIds() + >>> zs.shape + (32, 48) + >>> zs.getAxisIds() ['y', 'x'] - >>> >>> # lat and lon are also defined in terms of the cell axis - >>> lat.getAxisIds() + >>> lat.getAxisIds() ['y', 'x'] - >>> - >>> # lat and lon are one-dimensional, 'auxiliary' coordinate + >>> # lat and lon are one-dimensional, 'auxiliary' coordinate >>> # axes: values are not monotonic >>> lat.__class__ - - + + .. figure:: images/generic_grid.jpg :alt: generic grid @@ -606,7 +592,7 @@ representation. Similarly, a rectangular grid can be represented as curvilinear. The method toCurveGrid is used to convert a non-generic grid to curvilinear representation: -.. +:: >>> f = cdms2.open(cdat_info.get_sampledata_path()+'/clt.nc') >>> clt = f('clt') @@ -641,7 +627,7 @@ The built-in CDMS regridder is used to transform data from one rectangular grid to another. For example, to regrid variable ``u`` (from a rectangular grid) to a 96x192 rectangular Gaussian grid: -.. +:: >>> f = cdms2.open('clt.nc') >>> u = f('u') @@ -654,8 +640,8 @@ a rectangular grid) to a 96x192 rectangular Gaussian grid: To regrid a variable ``uold`` to the same grid as variable ``vnew``: -.. - +:: + >>> f = cdms2.open('clt.nc') >>> uold = f('u') >>> unew = f2('uwnd') @@ -697,21 +683,21 @@ For example, suppose the source data on a T42 grid is to be mapped to a POP curvilinear grid. Assume that SCRIP generated a remapping file named rmp_T42_to_POP43_conserv.nc: -.. - +:: + >>> # Import regrid package for regridder functions >>> import regrid2, cdms2 - + >>> # Get the source variable - >>> f = cdms2.open('sampleT42Grid.nc') - >>> dat = f('src_array') + >>> f = cdms2.open('sampleT42Grid.nc') + >>> dat = f('src_array') >>> f.close() - + >>> # Read the regridder from the remapper file - >>> remapf = cdms2.open('rmp_T42_to_POP43_conserv.nc') - >>> regridf = regrid2.readRegridder(remapf) + >>> remapf = cdms2.open('rmp_T42_to_POP43_conserv.nc') + >>> regridf = regrid2.readRegridder(remapf) >>> remapf.close() - + >>> # Regrid the source variable >>> popdat = regridf(dat) @@ -733,7 +719,7 @@ Relative time is time relative to a fixed base time. It consists of: For example, the time "28.0 days since 1996-1-1" has value= 28.0 , and units=" days since 1996-1-1". To create a relative time type: -.. +:: >>> import cdtime >>> rt = cdtime.reltime(28.0, "days since 1996-1-1") @@ -747,8 +733,7 @@ units=" days since 1996-1-1". To create a relative time type: A component time consists of the integer fields year, month, day, hour, minute , and the floating-point field second . For example: - -.. +:: >>> ct = cdtime.comptime(1996,2,28,12,10,30) >>> ct @@ -763,7 +748,7 @@ representations. For instance, suppose that the time axis of a variable is represented in units " days since 1979" . To find the coordinate value corresponding to January 1, 1990: -.. +:: >>> ct = cdtime.comptime(1990,1) >>> rt = ct.torel("days since 1979") @@ -774,8 +759,7 @@ Time values can be used to specify intervals of time to read. The syntax time=(c1,c2) specifies that data should be read for times t such that c1<=t<=c2: -.. - +:: >>> fh = cdms2.open(cdat_info.get_sampledata_path() + "/tas_6h.nc") >>> c1 = cdtime.comptime(1980,1) @@ -790,7 +774,7 @@ c1<=t<=c2: or string representations can be used: -.. +:: >>> fh = cdms2.open(cdat_info.get_sampledata_path() + "/tas_6h.nc") >>> tas = fh['tas'] @@ -813,15 +797,15 @@ To generate a plot: For example: -.. +:: >>> import cdms2, vcs, cdat_info >>> fh=cdms2.open(cdat_info.get_sampledata_path() + "/tas_cru_1979.nc") >>> fh['time'][:] # Print the time coordinates array([ 1476., 1477., 1478., 1479., 1480., 1481., 1482., 1483., 1484., 1485., 1486., 1487.]) - >>> - >>> tas = fh('tas', time=1479) + >>> + >>> tas = fh('tas', time=1479) >>> tas.shape (1, 36, 72) >>> w = vcs.init() # Initialize a canvas @@ -838,28 +822,4 @@ The plot routine has a number of options for producing different types of plots, such as isofill and x-y plots. See `Chapter 5 `__ for details. -Databases -^^^^^^^^^ - -Datasets can be aggregated together into hierarchical collections, -called databases . In typical usage, a program: - -- connects to a database -- searches for data opens a dataset -- accesses data - -Databases add the ability to search for data and metadata in a -distributed computing environment. At present CDMS supports one -particular type of database, based on the Lightweight Directory Access -Protocol (LDAP). - -Here is an example of accessing data via a database: - -:: - >>> db = cdms.connect() # Connect to the default database. - >>> f = db.open('ncep_reanalysis_mo') # Open a dataset. - >>> f.variables.keys() # List the variables in the dataset. -.. ['ua', 'evs', 'cvvta', 'tauv', 'wap', 'cvwhusa', 'rss', 'rls', ... 'prc', 'ts', 'va'] - -Databases are discussed further in `Section 2.7 `__. diff --git a/docs/source/manual/cdms_2.rst b/docs/source/manual/cdms_2.rst index c450b435..6b9f2596 100644 --- a/docs/source/manual/cdms_2.rst +++ b/docs/source/manual/cdms_2.rst @@ -48,13 +48,13 @@ return an instance of a CDMS class, or one of the Python types: PythonTypes used in CDMS ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Description" :widths: 10, 80 :align: left "Array", "Numpy or masked multidimensional data array. All elements of the array are of the same type. Defined in the Numpy and MV2 modules." - "Comptime", "Absolute time value, a time with representation (year, month, day, hour, minute, second). Defined in the cdtime module. cf. reltime" + "Comptime", "Absolute time value, a time with representation (year, month, day, hour, minute, second). Defined in the cdtime module. cf. reltime" "Dictionary","An unordered 2,3 collection of objects, indexed by key. All dictionaries in CDMS are indexed by strings, e.g.: ``axes['time']``" "Float", "Floating-point value." "Integer", "Integer value." @@ -71,8 +71,8 @@ data from an input dataset, averages over time, and writes the results to an output file. The input temperature data is ordered (time, latitude, longitude). -.. - +:: + >>> import cdms2, cdat_info >>> from cdms2 import MV >>> jones = cdms2.open(cdat_info.get_sampledata_path()+'/tas_mo.nc') @@ -95,7 +95,7 @@ latitude, longitude). >>> out.close() -.. csv-table:: +.. csv-table:: :header: "Line", "Notes" :widths: 10, 80 @@ -103,25 +103,25 @@ latitude, longitude). "4", "Opens a netCDF file read-only. The result jones is a dataset object." "5", "Gets the surface air temperature variable. ‘tas’ is the name of the variable in the input dataset. This does not actually read the data." - "6", "Read all January monthly mean data into a variable jans. + "6", "Read all January monthly mean data into a variable jans. * Variables can be sliced like arrays. * The slice operator [0::12] means take every 12th slice from dimension 0, starting at index 0 and ending at the last index. - * If the stride 12 were omitted, it would default to 1. - **Note:** That the variable is actually 3-dimensional. - * Since no slice is specified for the second or third dimensions, all values of those 2,3 dimensions are retrieved. + * If the stride 12 were omitted, it would default to 1. + **Note:** That the variable is actually 3-dimensional. + * Since no slice is specified for the second or third dimensions, all values of those 2,3 dimensions are retrieved. * The slice operation could also have been written [0::12, : , :]. - **Also Note:** That the same script works for multi-file datasets. + **Also Note:** That the same script works for multi-file datasets. * CDMS opens the needed data files, extracts the appropriate slices, and concatenates them into the result array." "7", "Reads all July data into a masked array julys." "8", "Calculate the average January value for each grid zone. Any missing data is handled automatically." - "9,10", "Set the variable id and long\_name attributes. + "9,10", "Set the variable id and long\_name attributes. * The id is used as the name of the variable when plotted or written to a file." "14", "Create a new netCDF output file named ‘janjuly.nc’ to hold the results." "15", "Write the January average values to the output file. * The variable will have id “tas\_jan” in the file. ``write`` is a utility function which creates the variable in - the file, then writes data to the variable. - * A more general method of data output is first to create a variable, then set a slice of the variable. + the file, then writes data to the variable. + * A more general method of data output is first to create a variable, then set a slice of the variable. **Note:** That janavg and julavg have the same latitude and longitude information as tasvar. It is carried along with the computations." "17", "Set the global attribute ‘comment’." @@ -136,24 +136,23 @@ Cdms Module The Cdms Module is the Python interface to CDMS. The objects and methods in this chapter are made accessible with the command: -.. doctest:: +:: - import cdms2 + >>> import cdms2 The functions described in this section are not associated with a class. Rather, they are called as module functions, e.g., -.. doctest:: - - file = cdms2.open('sample.nc') +:: + >>> file = cdms2.open('sample.nc') Cdms Module Functions --------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition" :widths: 10, 80 :align: left @@ -162,88 +161,88 @@ Cdms Module Functions "Variable", "``asVariable(s)``: Transform ``s`` into a transient variable. * ``s`` is a masked array, Numpy array, or Variable. - * If ``s`` is already a transient variable, ``s`` is returned. + * If ``s`` is already a transient variable, ``s`` is returned. * See also: ``isVariable``." "Axis", "``createAxis(data, bounds=None)``: - Create a one-dimensional coordinate Axis, which is not associated with a file or dataset. + Create a one-dimensional coordinate Axis, which is not associated with a file or dataset. This is useful for creating a grid which is not contained in a file or dataset. * ``data`` is a one-dimensional, monotonic Numpy array. * ``bounds`` is an array of shape ``(len(data),2)``, such that for all ``i`` * ``data[i]`` is in the range ``[bounds[i,0],bounds[i,1] ]``. - **Note:** + **Note:** - If ``bounds`` is not specified, the default boundaries are generated at - the midpoints between the consecutive data values, provided that the + the midpoints between the consecutive data values, provided that the autobounds mode is 'on' (the default). - * See ``setAutoBounds``. + * See ``setAutoBounds``. * Also see: ``CdmsFile.createAxis``" - "Axis", "``createEqualAreaAxis(nlat)``: - Create an equal-area latitude axis. + "Axis", "``createEqualAreaAxis(nlat)``: + Create an equal-area latitude axis. The latitude values range from north to south, and for all axis values ``x[i]``, ``sin(x[i])sin(x[i+1])`` is constant. - * ``nlat`` is the axis length. + * ``nlat`` is the axis length. **Note:** The axis is not associated with a file or dataset." - "Axis", "``createGaussianAxis(nlat)``: - Create a Gaussian latitude axis. + "Axis", "``createGaussianAxis(nlat)``: + Create a Gaussian latitude axis. Axis values range from north to south. * ``nlat`` is the axis length. **Note:** The axis is not associated with a file or dataset." "RectGrid", "``createGaussianGrid(nlats, xorigin=0.0, order='yx')``: - Create a Gaussian grid, with shape ``(nlats, 2*nlats)``. - * ``nlats`` is the number of latitudes. - * ``xorigin`` is the origin of the longitude axis. + Create a Gaussian grid, with shape ``(nlats, 2*nlats)``. + * ``nlats`` is the number of latitudes. + * ``xorigin`` is the origin of the longitude axis. * ``order`` is either 'yx' (lat-lon, default) or 'xy' (lon-lat)" - - + + Cdms Module Functions(cont'd) ----------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition" :widths: 10, 80 :align: left "RectGrid", "``createGenericGrid(latArray, lonArray, latBounds=None`` - ``lonBounds=None, order='yx', mask=None)``: + ``lonBounds=None, order='yx', mask=None)``: Create a generic grid, that is, a grid which is not typed as Gaussian, uniform, - or equal-area. - The grid is not associated with a file or dataset. + or equal-area. + The grid is not associated with a file or dataset. * ``latArray`` is a NumPy array of latitude values. - * ``lonArray`` is a NumPy array of longitude values. - * ``latBounds`` is a NumPy array having shape ``(len(latArray),2)``, of latitude boundaries. - * ``lonBounds`` is a NumPy array having shape ``(len(lonArray),2)``, of longitude boundaries. + * ``lonArray`` is a NumPy array of longitude values. + * ``latBounds`` is a NumPy array having shape ``(len(latArray),2)``, of latitude boundaries. + * ``lonBounds`` is a NumPy array having shape ``(len(lonArray),2)``, of longitude boundaries. * ``order`` is a ``string`` specifying the order of the axes, either 'yx' for (latitude, longitude), or 'xy' for the reverse. - * ``mask`` (optional) is an ``integer``-valued NumPy mask array, having the same shape and - ordering as the grid." + * ``mask`` (optional) is an ``integer``-valued NumPy mask array, having the same shape and + ordering as the grid." "RectGrid", "``createGlobalMeanGrid(grid)``: - Generate a grid for calculating the global mean via a regridding operation. - The return grid is a single zone covering the range of he input grid. + Generate a grid for calculating the global mean via a regridding operation. + The return grid is a single zone covering the range of he input grid. * ``grid`` is a RectGrid." "RectGrid", "``createRectGrid(lat, lon, order, type='generic', mask=None)``: Create a rectilinear grid, not associated with a file or dataset. - This might be used as the target grid for a regridding operation. - * ``lat`` is a latitude axis, created by ``cdms.createAxis``. - * ``lon`` is a longitude axis, created by ``cdms.createAxis``. + This might be used as the target grid for a regridding operation. + * ``lat`` is a latitude axis, created by ``cdms.createAxis``. + * ``lon`` is a longitude axis, created by ``cdms.createAxis``. * ``order`` is a string with value 'yx' (the first grid dimension is latitude) or 'xy' - (the first grid dimension is longitude). - * ``type`` is one of 'gaussian','uniform','equalarea',or 'generic'. + (the first grid dimension is longitude). + * ``type`` is one of 'gaussian','uniform','equalarea',or 'generic'. **Note:** If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) with the same shape as the grid." "RectGrid", "``createUniformGrid(startLat, nlat, deltaLat``, ``start-Lon, nlon, deltaLon, order='yx', mask=None)`` - Create a uniform rectilinear grid. - The grid is not associated with a file or dataset. - The grid boundaries are at the midpoints of the axis values. - * ``startLat`` is the starting latitude value. - * ``nlat`` is the number of latitudes. + Create a uniform rectilinear grid. + The grid is not associated with a file or dataset. + The grid boundaries are at the midpoints of the axis values. + * ``startLat`` is the starting latitude value. + * ``nlat`` is the number of latitudes. * If ``nlat`` is 1, the grid latitude boundaries will be ``startLat`` +/- ``deltaLat/2``. - * ``deltaLat`` is the increment between latitudes. + * ``deltaLat`` is the increment between latitudes. * ``startLon`` is the starting longitude value. - * ``nlon`` is the number of longitudes. + * ``nlon`` is the number of longitudes. * If ``nlon`` is 1, the grid longitude boundaries will be ``startLon`` +/- ``deltaLon/2``. - * ``deltaLon`` is the increment between longitudes. + * ``deltaLon`` is the increment between longitudes. * ``order`` is a string with value 'yx. (the first grid dimension is latitude) or .xy. (the first grid dimension is longitude). **Note:** If specified, ``mask`` is a two-dimensional, logical Numpy array (all values @@ -252,67 +251,67 @@ Cdms Module Functions(cont'd) Cdms Module Functions(cont'd) ----------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition" :widths: 10, 80 :align: left "Axis", "``createUniformLatitudeAxis(startLat , nlat, deltaLat)``: - Create a uniform latitude axis. - The axis boundaries are at the midpoints of the axis values. - The axis is designated as a circular latitude axis. + Create a uniform latitude axis. + The axis boundaries are at the midpoints of the axis values. + The axis is designated as a circular latitude axis. * ``startLat`` is the starting latitude value. * ``nlat`` is the number of latitudes. * ``deltaLat`` is the increment between latitudes." "RectGrid","``createZonalGrid(grid)``: - Create a zonal grid. + Create a zonal grid. The output grid has the same latitude as the input grid, and a single longitude. - This may be used to calculate zonal averages via a regridding operation. + This may be used to calculate zonal averages via a regridding operation. * ``grid`` is a RectGrid." - "Axis", "``createUniformLongitudeAxis(startLon, nlon, delta-Lon)``: + "Axis", "``createUniformLongitudeAxis(startLon, nlon, delta-Lon)``: Create a uniform longitude axis. - The axis boundaries are at the midpoints of the axis values. - The axis is designated as a circular longitude axis. + The axis boundaries are at the midpoints of the axis values. + The axis is designated as a circular longitude axis. * ``startLon`` is the starting longitude value. * ``nlon`` is the number of longitudes. * ``deltaLon`` is the increment between longitudes." "Variable", "``createVariable(array, typecode=None, copy=0, savespace=0, mask=None, fill_value=None, grid=None, axes=None , attributes=None, id=None)``:" - "Integer", "``getAutoBounds()``: + "Integer", "``getAutoBounds()``: Get the current autobounds mode. * Returns 0, 1, or 2. * See ``setAutoBounds``." - "Integer", "``isVariable(s)``: - * Return ``1`` if ``s`` is a variable, ``0`` otherwise. + "Integer", "``isVariable(s)``: + * Return ``1`` if ``s`` is a variable, ``0`` otherwise. * See also: ``asVariable``." - + Cdms Module Functions(cont'd) ----------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition" :widths: 10, 80 :align: left - "Dataset", "``open(url,mode='r')``: - Open or create a ``Dataset`` or ``CdmsFile``. + "Dataset", "``open(url,mode='r')``: + Open or create a ``Dataset`` or ``CdmsFile``. * ``url`` is a Uniform Resource Locator, referring to a cdunif or XML file. * If the URL has the extension '.xml' or '.cdml', a ``Dataset`` is returned, otherwise - a ``CdmsFile`` is returned. - * If the URL protocol is 'http', the file must be a '.xml' or '.cdml' file, and the mode must be 'r'. + a ``CdmsFile`` is returned. + * If the URL protocol is 'http', the file must be a '.xml' or '.cdml' file, and the mode must be 'r'. * If the protocol is 'file' or is omitted, a local file or dataset is opened. * ``mode`` is the open mode. See `Open Modes <#table-open-modes>`__ **Example:** Open an existing dataset: ``f = cdms.open('sampleset.xml')`` - **Example:** + **Example:** Create a netCDF file: ``f = cdms.open('newfile.nc','w')``" "List", "``order2index (axes, orderstring)``: - Find the index permutation of axes to match order. + Find the index permutation of axes to match order. * Return a list of indices. - * ``axes`` is a list of axis objects. + * ``axes`` is a list of axis objects. * ``orderstring`` is defined as in ``orderparse``." - "List", "``orderparse(orderstring)``: - Parse an order string. + "List", "``orderparse(orderstring)``: + Parse an order string. * Returns a list of axes specifiers. ``orderstring`` consists of: * Letters t, x, y, z meaning time, longitude, latitude, level @@ -320,39 +319,39 @@ Cdms Module Functions(cont'd) * Dash (-) meaning insert the next available axis here. * The ellipsis ... meaning fill these positions with any remaining axes. * (name) meaning an axis whose id is name" - + Cdms Module Functions(cont'd) ----------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition" :widths: 10, 80 :align: left - "None", "``setAutoBounds(mode)``: + "None", "``setAutoBounds(mode)``: Set autobounds mode. In some circumstances CDMS can generate boundaries for 1-D axes and rectilinear grids, when the bounds are not explicitly defined. The autobounds mode determines how this is done: - * If ``mode`` is ``'grid'`` or ``2`` (the default), the ``getBounds`` method will automatically + * If ``mode`` is ``'grid'`` or ``2`` (the default), the ``getBounds`` method will automatically generate boundary information for an axis or grid if the axis is designated as a latitude or - longitude axis, and the boundaries are not explicitly defined. + longitude axis, and the boundaries are not explicitly defined. * If ``mode`` is ``'on'`` or ``1``, the ``getBounds`` method will automatically generate boundary information for an axis or grid, if the boundaries are not explicitly defined. - * If ``mode`` is ``'off'`` or ``0``, and no boundary data is explicitly defined, the bounds will - NOT be generated; the ``getBounds`` method will return ``None`` for the boundaries. + * If ``mode`` is ``'off'`` or ``0``, and no boundary data is explicitly defined, the bounds will + NOT be generated; the ``getBounds`` method will return ``None`` for the boundaries. **Note:** In versions of CDMS prior to V4.0, the default ``mode`` was ``'on'``." "None", "``setClassifyGrids(mode)``: - Set the grid classification mode. + Set the grid classification mode. This affects how grid type is determined, for the purpose of generating grid boundaries. - * If ``mode`` is ``'on'`` (the default), grid type is determined by a grid classification method, + * If ``mode`` is ``'on'`` (the default), grid type is determined by a grid classification method, regardless of the value of ``grid.get-Type()``. - * If ``mode`` is ``'off'``, the value of ``grid.getType()`` determines the grid type." + * If ``mode`` is ``'off'``, the value of ``grid.getType()`` determines the grid type." "None", "``writeScripGrid(path, grid, gridTitle=None)``: - Write a grid to a SCRIP grid file. - * ``path`` is a string, the path of the SCRIP file to be created. + Write a grid to a SCRIP grid file. + * ``path`` is a string, the path of the SCRIP file to be created. * ``grid`` is a CDMS grid object. It may be rectangular. ``gridTitle`` is a string ID for the grid." @@ -360,10 +359,10 @@ Cdms Module Functions(cont'd) Class Tags ---------- -.. csv-table:: +.. csv-table:: :header: "Tag", "Class" :widths: 20, 20 - + "‘axis’", "Axis" "‘database’", "Database" "‘dataset’", "Dataset, CdmsFile " @@ -389,13 +388,11 @@ external attributes are written, but not the internal attributes. **Example**: Get a list of all external attributes of obj. -.. doctest:: - Attributes Common to All CDMS Objects ------------------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Name", "Definition" :widths: 20, 20, 50 @@ -404,17 +401,17 @@ Attributes Common to All CDMS Objects Getting and Setting Attributes ------------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Definition" :widths: 20, 80 "various", "``value = obj.attname`` Get an internal or external attribute value. * If the attribute is external, it is read from the database. - * If the attribute is not already in the database, it is created as an external attribute. + * If the attribute is not already in the database, it is created as an external attribute. **Note:** Internal attributes cannot be created, only referenced." "various", "``obj.attname = value`` - Set an internal or external attribute value. + Set an internal or external attribute value. * If the attribute is external, it is written to the database." @@ -437,30 +434,30 @@ Axis objects. CoordinateAxis Types -------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition" :widths: 20, 80 - "CoordinateAxis", "A variable that represents coordinate information. + "CoordinateAxis", "A variable that represents coordinate information. * Has subtypes ``Axis2D`` and ``AuxAxis1D``." "Axis", "A one-dimensional coordinate axis whose values are strictly monotonic. - * Has subtypes ``DatasetAxis``, ``FileAxis``, and ``TransientAxis``. - * May be an index axis, mapping a range of integers to the equivalent floating point value. + * Has subtypes ``DatasetAxis``, ``FileAxis``, and ``TransientAxis``. + * May be an index axis, mapping a range of integers to the equivalent floating point value. * If a latitude or longitude axis, may be associated with a ``RectGrid``." "Axis2D", "A two-dimensional coordinate axis, typically a latitude or longitude axis related - to a ``CurvilinearGrid``. + to a ``CurvilinearGrid``. * Has subtypes ``DatasetAxis2D``, ``FileAxis2D``, and ``TransientAxis2D``." "AuxAxis1D", "A one-dimensional coordinate axis whose values need not be monotonic. * Typically a latitude or longitude axis associated with a ``GenericGrid``. - * Has subtypes ``DatasetAuxAxis1D``, ``FileAuxAxis1D``, and ``TransientAuxAxis1D``. - * An axis in a ``CdmsFile`` may be designated the unlimited axis, meaning that it can - be extended in length after the initial definition. + * Has subtypes ``DatasetAuxAxis1D``, ``FileAuxAxis1D``, and ``TransientAuxAxis1D``. + * An axis in a ``CdmsFile`` may be designated the unlimited axis, meaning that it can + be extended in length after the initial definition. * There can be at most one unlimited axis associated with a ``CdmsFile``." CoordinateAxis Internal Attributes ---------------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Name", "Definition" :widths: 30, 20, 80 @@ -472,19 +469,19 @@ CoordinateAxis Internal Attributes Axis Constructors ----------------- -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 20, 80 - "``cdms.createAxis (data, bounds=None)``", "Create an axis which is not associated with a dataset or file. + "``cdms.createAxis (data, bounds=None)``", "Create an axis which is not associated with a dataset or file. * See `A First Example <#a-first-example>`_." "``Dataset.createAxis (name,ar)``", "Create an ``Axis`` in a ``Dataset``. (This function is not yet implemented.)" "``CdmsFile.createAxis (name,ar,unlimited=0)``", "Create an Axis in a ``CdmsFile``. - * ``name`` is the string ``name`` of the ``Axis``. + * ``name`` is the string ``name`` of the ``Axis``. * ``ar`` is a 1-D data array which defines the ``Axis`` values. * It may have the value ``None`` if an unlimited axis is being defined. - * At most one ``Axis`` in a ``CdmsFile`` may be designated as being unlimited, meaning that it may - be extended in length. + * At most one ``Axis`` in a ``CdmsFile`` may be designated as being unlimited, meaning that it may + be extended in length. To define an axis as unlimited, either: * A) set ``ar`` to ``None``, and leave ``unlimited`` undefined, or * B) set ``ar`` to the initial 1-D array, and set ``unlimited`` to ``cdms.Unlitmited`` @@ -501,54 +498,54 @@ Axis Constructors CoordinateAxis Methods ---------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 15, 32, 80 :align: left - + "Array", ``array = axis[i:j]``", "Read a slice of data from the external file or dataset. - * Data is returned in the physical ordering defined in the dataset. + * Data is returned in the physical ordering defined in the dataset. * See `Variable Slice Operators <#table-variable-slice-operators>`_ for a description of slice operators." - "None", "``axis[i:j] = array``", "Write a slice of data to the external file. + "None", "``axis[i:j] = array``", "Write a slice of data to the external file. * Dataset axes are read-only." - "None", "``assignValue(array)``", "Set the entire value of the axis. + "None", "``assignValue(array)``", "Set the entire value of the axis. * ``array`` is a Numpy array, of the same dimensionality as the axis." "Axis", "``clone(copyData=1)``", "Return a copy of the axis, as a transient axis. * If copyData is 1 (the default) the data itself is copied." "None", "``designateLatitude (persistent=0)``", "Designate the axis to be a latitude axis. - * If persistent is true, the external file or dataset (if any) is modified. + * If persistent is true, the external file or dataset (if any) is modified. * By default, the designation is temporary." "None", "``designateLevel (persistent=0)``", "Designate the axis to be a vertical level axis. - * If persistent is true, the external file or dataset (if any) is modified. + * If persistent is true, the external file or dataset (if any) is modified. * By default, the designation is temporary." - "None", "``designateLongitude (persistent=0, modulo=360.0)``", "Designate the axis to be a longitude axis. + "None", "``designateLongitude (persistent=0, modulo=360.0)``", "Designate the axis to be a longitude axis. * ``modulo`` is the modulus value. * Any given axis value ``x`` is treated as equivalent to ``x + modulus``. - * If ``persistent`` is true, the external file or dataset (if any) is modified. + * If ``persistent`` is true, the external file or dataset (if any) is modified. * By default, the designation is temporary." - "None", "``designateTime (persistent=0, calendar = cdtime.MixedCalendar)``", "Designate the axis to be a time axis. + "None", "``designateTime (persistent=0, calendar = cdtime.MixedCalendar)``", "Designate the axis to be a time axis. * If ``persistent`` is true, the external file or dataset (if any) is modified. - * By default, the designation is temporary. + * By default, the designation is temporary. * ``calendar`` is defined as in ``getCalendar()``." CoordinateAxis Methods(cont'd) ------------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 15, 30, 80 :align: left - "Array", "``getBounds()``", "Get the associated boundary array. + "Array", "``getBounds()``", "Get the associated boundary array. The shape of the return array depends on the type of axis: * ``Axis``: ``(n,2)`` * ``Axis2D``: ``(i,j,4)`` * ``AuxAxis1D``: ``(ncell, nvert)`` where nvert is the maximum number of vertices of a cell. - If the boundary array of a latitude or longitude - * ``Axis`` is not explicitly defined, and ``autoBounds`` mode is on, a default array is generated by calling ``genGenericBounds``. + If the boundary array of a latitude or longitude + * ``Axis`` is not explicitly defined, and ``autoBounds`` mode is on, a default array is generated by calling ``genGenericBounds``. * Otherwise if auto-Bounds mode is off, the return value is ``None``. * See ``setAutoBounds``." "Integer", "``getCalendar()``", "Returns the calendar associated with the ``(time)``\ axis. @@ -573,17 +570,17 @@ CoordinateAxis Methods(cont'd) Axis Methods, Additional to CoordinateAxis ------------------------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left - "List of component times", "``asComponentTime (calendar=None)``", "``Array`` version of ``cdtime tocomp``. + "List of component times", "``asComponentTime (calendar=None)``", "``Array`` version of ``cdtime tocomp``. * Returns a ``List`` of component times." "List of relative times", "``asRelativeTime()``", "``Array`` version of ``cdtime torel``. * Returns a ``List`` of relative times." - "None", "``designate Circular( modulo, persistent=0)``", "Designate the axis to be circular. + "None", "``designate Circular( modulo, persistent=0)``", "Designate the axis to be circular. * ``modulo`` is the modulus value. * Any given axis value ``x`` is treated as equivalent to ``x + modulus``. * If ``persistent`` is ``True``, the external file or dataset (if any) is modified. @@ -591,7 +588,7 @@ Axis Methods, Additional to CoordinateAxis "Integer", "``isCircular()``", "Returns ``True`` if the axis has circular topology. An axis is defined as circular if: * ``axis.topology == 'circular'``, or - * ``axis.topology`` is undefined, and the axis is a longitude. + * ``axis.topology`` is undefined, and the axis is a longitude. * The default cycle for circular axes is 360.0" "Integer", "``isLinear()``", "Returns ``True`` if the axis has a linear representation." "Tuple", "``mapInterval (interval)``", "Same as ``mapIntervalExt``, but returns only the tuple @@ -600,7 +597,7 @@ Axis Methods, Additional to CoordinateAxis Axis Methods, Additional to CoordinateAxis(cont'd) -------------------------------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left @@ -614,32 +611,32 @@ Axis Methods, Additional to CoordinateAxis(cont'd) Where ``x`` and ``y`` are coordinates indicating the interval ``[x,y]``, and: * ``indicator`` is a two or three-character string, where the first character is ``'c'`` if - the interval is closed on the left, ``'o'`` if open, and the second character has the same - meaning for the right-hand point. If present, the third character specifies how the interval + the interval is closed on the left, ``'o'`` if open, and the second character has the same + meaning for the right-hand point. If present, the third character specifies how the interval should be intersected with the axis * ``'n'`` - select node values which are contained in the interval * ``'b'`` -select axis elements for which the corresponding cell boundary intersects the interval * ``'e'`` - same as n, but include an extra node on either side * ``'s'`` - select axis elements for which the cell boundary is a subset of the interval * The default indicator is ‘ccn’, that is, the interval is closed, and nodes in the interval are selected. - * If ``cycle`` is specified, the axis is treated as circular with the given cycle value. + * If ``cycle`` is specified, the axis is treated as circular with the given cycle value. * By default, if ``axis.isCircular()`` is true, the axis is treated as circular with a default modulus of ``360.0``. * An interval of ``None`` or ``':'`` returns the full index interval of the axis. * The method returns the corresponding index interval as a 3tuple ``(i,j,k)``, where ``k`` is the integer stride, - and ``[i.j)`` is the half-open index interval ``i <= k < j`` ``(i >= k > j if k < 0)``, or ``none`` if the + and ``[i.j)`` is the half-open index interval ``i <= k < j`` ``(i >= k > j if k < 0)``, or ``none`` if the intersection is empty. * If ``0 <= i < n`` and ``0 <= j <= n``, the interval does not wrap around the axis endpoint. * Otherwise the interval wraps around the axis endpoint. * See also: ``mapinterval``, ``variable.subregion()``" "transient axis", "``subaxis(i,j,k=1)``", "Create an axis associated with the integer range - ``[i:j:k]``. + ``[i:j:k]``. * The stride ``k`` can be positive or negative. - * Wraparound is supported for longitude dimensions or those with a modulus attribute." + * Wraparound is supported for longitude dimensions or those with a modulus attribute." Axis Slice Operators -------------------- -.. csv-table:: +.. csv-table:: :header: "Slice", "Definition" :widths: 50, 110 @@ -653,15 +650,16 @@ Axis Slice Operators **Example:** a longitude axis has value * ``[0.0, 2.0, ..., 358.0]`` * of length ``180`` - Map the coordinate interval: - * ``-5.0 <= x < 5.0`` to index interval(s), with wraparound. the result index interval - * ``-2 <= n < 3`` wraps around, since - * ``-2 < 0``, and has a stride of ``1`` - * This is equivalent to the two contiguous index intervals + Map the coordinate interval: + * ``-5.0 <= x < 5.0`` to index interval(s), with wraparound. the result index interval + * ``-2 <= n < 3`` wraps around, since + * ``-2 < 0``, and has a stride of ``1`` + * This is equivalent to the two contiguous index intervals * ``2 <= n < 0`` and ``0 <= n < 3``" Example 1 ''''''''''' + :: >>> axis.isCircular() @@ -684,7 +682,7 @@ Cdms-Files. See “cu Module”. CdmsFile Internal Attributes ---------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Name", "Definition" :widths: 30, 20, 80 @@ -697,21 +695,21 @@ CdmsFile Internal Attributes CdmsFile Constructors --------------------- -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 50, 80 :align: left "Constructor", "Description" - "``fileobj = cdms.open(path, mode)``", "Open the file specified by path returning a CdmsFile object. - * ``path`` is the file pathname, a string. - * ``mode`` is the open mode indicator, as listed in `Open Modes <#table-open-modes>`_." + "``fileobj = cdms.open(path, mode)``", "Open the file specified by path returning a CdmsFile object. + * ``path`` is the file pathname, a string. + * ``mode`` is the open mode indicator, as listed in `Open Modes <#table-open-modes>`_." "``fileobj = cdms.createDataset(path)``", "Create the file specified by path, a string." CdmsFile Methods ---------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 35, 32, 80 :align: left @@ -719,7 +717,7 @@ CdmsFile Methods "Transient-Variable", "``fileobj(varname, selector)``", "Calling a ``CdmsFile`` object as a function reads the region of data specified by the ``selector``. - The result is a transient variable, unless ``raw = 1`` is specified. + The result is a transient variable, unless ``raw = 1`` is specified. See `Selectors <#selectors>`_. **Example:** The following reads data for variable 'prc', year 1980: @@ -733,104 +731,104 @@ CdmsFile Methods >>> v = f.variables['prc'] >>> f = cdms.open('sample.nc') >>> v = f['prc'] - **Example:** The following gets the axis named time, + **Example:** The following gets the axis named time, equivalent to >>> t = f.axes['time'] >>> t = f['time']" "None", "``close()``", "Close the file." - "Axis", "``copyAxis(axis, newname=None)``", "Copy ``axis`` values and attributes to a new axis in the file. + "Axis", "``copyAxis(axis, newname=None)``", "Copy ``axis`` values and attributes to a new axis in the file. The returned object is persistent: it can be used to write axis data to or read axis data from the file. - * If an axis already exists in the file, having the same name and coordinate values, it is returned. + * If an axis already exists in the file, having the same name and coordinate values, it is returned. * It is an error if an axis of the same name exists, but with different coordinate values. - * ``axis`` is the axis object to be copied. - * ``newname``, if specified, is the string identifier of the new axis object. + * ``axis`` is the axis object to be copied. + * ``newname``, if specified, is the string identifier of the new axis object. * If not specified, the identifier of the input axis is used." - + CdmsFile Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 35, 30, 80 :align: left - "Grid", "``copyGrid(grid, newname=None)``", "Copy grid values and attributes to a new grid in the file. + "Grid", "``copyGrid(grid, newname=None)``", "Copy grid values and attributes to a new grid in the file. The returned grid is persistent. * If a grid already exists in the file, having the same name and axes, it is returned. - * An error is raised if a grid of the same name exists, having different axes. - * ``grid`` is the grid object to be copied. - * ``newname``, if specified is the string identifier of the new grid object. + * An error is raised if a grid of the same name exists, having different axes. + * ``grid`` is the grid object to be copied. + * ``newname``, if specified is the string identifier of the new grid object. * If unspecified, the identifier of the input grid is used." - "Axis", "``createAxis(id,ar, unlimited=0)``", "Create a new ``Axis``. + "Axis", "``createAxis(id,ar, unlimited=0)``", "Create a new ``Axis``. This is a persistent object which can be used to read or write axis data to the file. - * ``id`` is an alphanumeric string identifier, containing no blanks. + * ``id`` is an alphanumeric string identifier, containing no blanks. * ``ar`` is the one-dimensional axis array. * Set ``unlimited`` to ``cdms.Unlimited`` to indicate that the axis is extensible." "RectGrid", "``createRectGrid (id,lat, lon,order,type='generic', mask=None)``", "Create a ``RectGrid`` in the file. This is not a persistent object: the order, type, and mask are not written to the file. However, - the grid may be used for regridding operations. - * ``lat`` is a latitude axis in the file. - * ``lon`` is a longitude axis in the file. - * ``order`` is a string with value ``'yx'`` (the latitude) or ``'xy'`` (the first grid dimension - is longitude). + the grid may be used for regridding operations. + * ``lat`` is a latitude axis in the file. + * ``lon`` is a longitude axis in the file. + * ``order`` is a string with value ``'yx'`` (the latitude) or ``'xy'`` (the first grid dimension + is longitude). * ``type`` is one of ``'gaussian'``,\ ``'unif orm'``,\ ``'equalarea'`` , or ``'generic'``. - * If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) + * If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) with the same shape as the grid." - + CdmsFile Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 20, 35, 80 :align: left - "Variable", "``createVariable (Stringid,String datatype,Listaxes,fill_value=None)``", "Create a new Variable. - This is a persistent object which can be used to read + "Variable", "``createVariable (Stringid,String datatype,Listaxes,fill_value=None)``", "Create a new Variable. + This is a persistent object which can be used to read or write variable data to the file. * ``id`` is a String name which is unique with respect to all other objects in the file. - * ``datatype`` is an ``MV2`` typecode, e.g., ``MV2.Float``, ``MV2.Int``. - * ``axes`` is a list of Axis and/or Grid objects. + * ``datatype`` is an ``MV2`` typecode, e.g., ``MV2.Float``, ``MV2.Int``. + * ``axes`` is a list of Axis and/or Grid objects. * ``fill_value`` is the missing value (optional)." "Variable", "``createVariableCopy (var, newname=None)``", "Create a new ``Variable``, with the same name, axes, and - attributes as the input variable. An error is raised if a + attributes as the input variable. An error is raised if a variable of the same name exists in the file. - * ``var`` is the ``Variable`` to be copied. - * ``newname``, if specified is the name of the new variable. + * ``var`` is the ``Variable`` to be copied. + * ``newname``, if specified is the name of the new variable. * If unspecified, the returned variable has the same name as ``var``. **Note:** Unlike copyAxis, the actual data is not copied to the new variable." "CurveGrid or Generic-Grid", "``readScripGrid (self,whichGrid= 'destination',check-Grid=1)``", "Read a curvilinear or generic grid from a SCRIP netCDF file. - The file can be a SCRIP grid file or remapping file. + The file can be a SCRIP grid file or remapping file. - * If a mapping file, ``whichGrid`` chooses the grid to read, either ``'source'`` or ``'destination'``. - * If ``checkGrid`` is ``1`` (default), the grid cells are checked for convexity, and 'repaired' if necessary. - * Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. + * If a mapping file, ``whichGrid`` chooses the grid to read, either ``'source'`` or ``'destination'``. + * If ``checkGrid`` is ``1`` (default), the grid cells are checked for convexity, and 'repaired' if necessary. + * Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. * The repair consists of shifting the cell vertices to the same side modulo 360 degrees." - + CdmsFile Methods(cont'd) ---------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left "None", "``sync()``", "Writes any pending changes to the file." - "Variable", "``write(var,attributes=None,axes=None, extbounds=None,id=None,extend=None, fill_value=None, index=None, typecode=None)``","Write a variable or array to the file. + "Variable", "``write(var,attributes=None,axes=None, extbounds=None,id=None,extend=None, fill_value=None, index=None, typecode=None)``","Write a variable or array to the file. The return value is the associated file variable. - * If the variable does not exist in the file, it is first defined and all attributes written, then the data is written. + * If the variable does not exist in the file, it is first defined and all attributes written, then the data is written. * By default, the time dimension of the variable is defined as the unlimited dimension of the file. * If the data is already defined, then data is extended or overwritten depending on the value of keywords ``extend`` and ``index``, and the unlimited dimension values associated with ``var``. * ``var`` is a Variable, masked array, or Numpy array. * ``attributes`` is the attribute dictionary for the variable. The default is ``var.attributes``. - * ``axes`` is the list of file axes comprising the domain of the variable. + * ``axes`` is the list of file axes comprising the domain of the variable. * The default is to copy ``var.getAxisList()``. * ``extbounds`` is the unlimited dimension bounds. Defaults to ``var.getAxis(0).getBounds()``. * ``id`` is the variable name in the file. Default is ``var.id``. - * ``extend = 1`` causes the first dimension to be unlimited: iteratively writeable. + * ``extend = 1`` causes the first dimension to be unlimited: iteratively writeable. * The default is ``None``, in which case the first dimension is extensible if it is ``time.Set`` to ``0`` to turn off this behaviour. * ``fill_value`` is the missing value flag. * ``index`` is the extended dimension index to write to. The default index is determined by lookup relative to the existing extended dimension. @@ -839,7 +837,7 @@ CdmsFile Methods(cont'd) CDMS Datatypes -------------- -.. csv-table:: +.. csv-table:: :header: "CDMS Datatype", "Definition" :widths: 20, 30 @@ -851,418 +849,6 @@ CDMS Datatypes "CdShort", "short integer" -Database -^^^^^^^^ -A Database is a collection of datasets and other CDMS objects. It -consists of a hierarchical collection of objects, with the database -being at the root, or top of the hierarchy. A database is used to: - -- search for metadata -- access data -- provide authentication and access control for data and metadata - -The figure below illustrates several important points: - -- Each object in the database has a relative name of the form tag=id. - The id of an object is unique with respect to all objects contained - in the parent. - -- The name of the object consists of its relative name followed by the - relative name(s) of its antecedent objects, up to and including the - database name. In the figure below, one of the variables has name - ``"variable=ua,dataset=ncep_reanalysis_mo,database=CDMS"``. - -- Subordinate objects are thought of as being contained in the parent. - In this example, the database ‘CDMS’ contains two datasets, each of - which contain several variables. - -%|Diagram 1| - -Figure 1 - - -Overview --------------- - -To access a database: - -#. Open a connection. - The connect method opens a database connection. - Connect takes a database URI and returns a database object: - ``db=cdms.connect("ldap://dbhost.llnl.gov/database=CDMS,ou=PCMDI,o=LLNL,c=US")`` - -#. Search the database, locating one or more datasets, variables, and/or - other objects. - - The database searchFilter method searches the database. A single - database connection may be used for an arbitrary number of searches. - - **Example**: Find all observed datasets - - ``result = db.searchFilter(category="observed",tag="dataset")`` - - Searches can be restricted to a subhierarchy of the database. - - **Example:** Search just the dataset ``'ncep_reanalysis_mo'``: - - ``result = db.searchFilter(relbase="dataset=ncep_reanalysis")`` - -#. Refine the search results if necessary. The result of a search can be - narrowed with the searchPredicate method. -#. Process the results. A search result consists of a sequence of - entries. Each entry has a name, the name of the CDMS object, and an - attribute dictionary, consisting of the attributes located by the - search: - - `` for entry in result: print entry.name, entry.attributes`` - -#. Access the data. The CDMS object associated with an entry is obtained - from the getObject method: - - ``obj = entry.getObject()`` - - If the id of a dataset is known, the dataset can be opened directly - with the open method: - - ``dset = db.open("ncep_reanalysis_mo")`` - -#. Close the database connection: - - ``db.close()`` - -Database Internal Attributes ----------------------------- - - -.. csv-table:: - :header: "Type", "Name", "Summary" - :widths: 30, 20, 80 - - "Dictionary", "``attributes``", "Database attribute dictionary" - "LDAP", "``db``", "(LDAP only) LDAP database object" - "String", "``netloc``", "Hostname, for server-based databases" - "String", "``path``", "path name" - "String", "``uri``", "Uniform Resource Identifier" - - -Database Constructors ---------------------- - -.. csv-table:: - :header: "Constructor", "Description" - :widths: 30, 80 - :align: left - - - "``db = cdms.connect(uri=None, user='', password='')``", "Connect to the database. - * ``uri`` is the Universal Resource Indentifier of the database. - * The form of the URI depends on the implementation of the database. - * For a Lightweight Directory Access Protocol (LDAP) database, the form is: ``ldap://host[:port]/dbname``. - For example, if the database is located on host dbhost.llnl.gov, and is - named ``'database=CDMS,ou=PCMDI,o=LLNL,c=US'``, the URI is: - * ``ldap://dbhost.llnl.gov/database=CDMS,ou=PCMDI,o=LLNL,c=US``. - * If unspecified, the URI defaults to the value of environment variable CDMSROOT. - * ``user`` is the user ID. If unspecified, an anonymous connection is made. - * ``password`` is the user password. - **Note:** A password is not required for an anonymous connection" - -Database Methods ----------------- - -.. csv-table:: - :header: "Type", "Method", "Definition" - :widths: 20, 32, 90 - - "None", "``close()``", "Close a database" - "List", "``listDatasets()``", "Return a list of the dataset IDs in this database. A dataset ID can be passed to the ``open`` command." - "Dataset", "``open(dsetid, mode='r')``", "Open a dataset. - * ``dsetid`` is the string dataset identifier - * ``mode`` is the open mode, 'r' - read-only, 'r+' - read-write, 'w' - create. - * ``openDataset`` is a synonym for ``open``." - "SearchResult","``searchFilter (filter=None, tag=None, relbase=None, scope=Subtree, attnames=None, timeout=None)``","Search a CDMS database. - * ``filter`` is the string search filter. - * Simple filters have the form 'tag = value'. - * Simple filters can be combined using logical operators '&', '\|', '!' in prefix notation. - **Example:** - * The filter ``'(&(objec)(id=cli))'`` finds all variables named 'cli'. - * A formal definition of search filters is provided in the following section. - * ``tag`` restricts the search to objects with that tag ('dataset' | 'variable' | 'database' | 'axis' | 'grid'). - * ``relbase`` is the relative name of the base object of the search. The search is restricted to the base object and all objects - below it in the hierarchy. - **Example:** - To search only dataset 'ncep_reanalysis_mo', specify: - * ``relbase='dataset=ncep_reanalysis_mo'`` - o search only variable 'ua' in 'ncep_reanalysis_mo', use: - * ``relbase='variable=ua, dataset=ncep_reanalysis_mo'`` - If no base is specified, the entire database is searched. - See the ``scope`` argument also. - * ``scope`` is the search scope (**Subtree** | **Onelevel** | **Base**). - * **Subtree** searches the base object and its descendants. - * **Onelevel** searches the base object and its immediate descendants. - * **Base** searches the base object alone. - * The default is **Subtree**. - * ``attnames``: list of attribute names. Restricts the attributes returned. - * If ``None``, all attributes are returned. - * Attributes 'id' and 'objectclass' are always included in the list. - * ``timeout``: integer number of seconds before timeout. The default is no timeout." - - -Searching a Database --------------------------- - -.. csv-table:: - :header: "Type", "Name", "Summary" - :widths: 30, 20, 80 - - "Dictionary", "``attributes``", "Database attribute dictionary" - "LDAP", "``db``", "(LDAP only) LDAP database object" - "String", "``netloc``", "Hostname, for server-based databases" - "String", "``path``", "path name" - "String", "``uri``", "Uniform Resource Identifier" - -:: - - (id = ncep*) - (project = AMIP2) - -**Note:** Simple filters can be combined with the logical operators '&', '|', '!'. For example, - - * ``mode``, is the open mode, 'r' - read-only, 'r+' - read-write, 'w' - create. - -(&(id = bmrc*)(project = AMIP2)) - - - * To search only dataset 'ncep_reanalysis_mo', specify: - * ``relbase='dataset=ncep_reanalysis_mo'`` - * To search only variable 'ua' in 'ncep_reanalysis_mo', use: - * ``relbase='variable=ua, dataset=ncep_reanalysis_mo'`` - If no base is specified, the entire database is searched. See the ``scope`` argument also. - - * ``scope`` is the search scope (**Subtree** | **Onelevel** | **Base**). - * **Subtree** searches the base object and its descendants. - * **Onelevel** searches the base object and its immediate descendants. - * **Base**\ searches the base object alone. - * The default is **Subtree**. - * ``attnames``: list of attribute names. Restricts the attributes returned. If ``None``, all attributes are returned. Attributes 'id' and 'objectclass' are always included in the list. - * ``timeout``: integer number of seconds before timeout. The default is no timeout." - - -:: - - >>> (&(id = bmrc*)(project = AMIP2)) - - -Matches all objects with id starting with bmrc, and a project attribute -with value ‘AMIP2’. - -Formally, search filters are strings defined as follows: - -:: - - -Attribute names are defined in the chapter on “Climate Data Markup -Language (CDML)”. In addition, some special attributes are -defined for convenience: - -- ``category`` is either “experimental” or “observed” -- ``parentid`` is the ID of the parent dataset -- ``project`` is a project identifier, e.g., “AMIP2” -- ``objectclass`` is the list of tags associated with the object. - -The set of objects searched is called the search scope. The top object -in the hierarchy is the base object. By default, all objects in the -database are searched, that is, the database is the base object. If the -database is very large, this may result in an unnecessarily slow or -inefficient search. To remedy this the search scope can be limited in -several ways: - -- The base object can be changed. -- The scope can be limited to the base object and one level below, or - to just the base object. -- The search can be restricted to objects of a given class (dataset, - variable, etc.) -- The search can be restricted to return only a subset of the object - attributes -- The search can be restricted to the result of a previous search. -- A search result is accessed sequentially within a for loop: - -:: - - >>> result = db.searchFilter('(&(category=obs*)(id=ncep*))') - >>> for entry in result: - >>> print entry.name - -Search results can be narrowed using ``searchPredicate``. In the -following example, the result of one search is itself searched for all -variables defined on a 94x192 grid: - -:: - - >>> result = db.searchFilter('parentid=ncep*',tag="variable") - >>> len(result) - 65 - >>> result2 = result.searchPredicate(lambda x: - >>> - x.getGrid().shape==(94,192)) - >>> len(result2) - 3 - >>> for entry in result2: print entry.name - variable=rluscs,dataset=ncep_reanalysis_mo,database=CDMS,ou=PCMDI, - >>> - o=LLNL, c=US - variable=rlds,dataset=ncep_reanalysis_mo,database=CDMS,ou=PCMDI, - >>> - o=LLNL, c=US - variable=rlus,dataset=ncep_reanalysis_mo,database=CDMS,ou=PCMDI, - >>> - o=LLNL, c=US - - - -SearchResult Methods --------------------- - -.. csv-table:: - :header: "Type", "Method", "Definition" - :widths: 20, 30, 80 - - "ResultEntry", "``[i]``", "Return the i-th search result. Results can also be returned in a for loop: ``for entry in db.searchResult(tag='dataset'):``" - "Integer", "``len()``", "Number of entries in the result." - "SearchResult", "``searchPredicate (predicate, tag=None)``", "Refine a search result, with a predicate search. - * ``predicate`` is a function which takes a single CDMS object and returns true (1) if the object satisfies the predicate, 0 if not. - * ``tag`` restricts the search to objects of the class denoted by the tag. - **Note:**: In the current implementation, ``searchPredicate`` is much less efficient than ``searchFilter``. For best performance, use ``searchFilter`` to narrow the scope of the search, then use ``searchPredicate`` for more general searches." - -A search result is a sequence of result entries. Each entry has a string -name, the name of the object in the database hierarchy, and an attribute -dictionary. An entry corresponds to an object found by the search, but -differs from the object, in that only the attributes requested are -associated with the entry. In general, there will be much more -information defined for the associated CDMS object, which is retrieved -with the ``getObject`` method. - - -ResultEntry Attributes ----------------------- - -.. csv-table:: - :header: "Type", "Method", "Definition" - :widths: 20, 30, 80 - - "String", "``name``", "The name of this entry in the database." - "Dictionary", "``attributes``", "The attributes returned from the search. ``attributes[key]`` is a list of all string values associated with the key" - - -ResultEntry Methods -------------------- - -.. csv-table:: - :header: "Type", "Method", "Definition" - :widths: 20, 30, 80 - - "CdmsObj", "``getObject()``", "Return the CDMS object associated with this entry. - **Note:** For many search applications it is unnecessary to access the associated CDMS object. For best performance this function should be used only when necessary, for example, to retrieve data associated with a variable." - "CdmsObj", "``getObject()``", "Return the CDMS object associated with this entry. - **Note:** For many search applications it is unnecessary to access the associated CDMS object. For best performance this function should be used only when necessary, for example, to retrieve data associated with a variable." - -Accessing Data --------------------- - -To access data via CDMS: - -#. Locate the dataset ID. This may involve searching the metadata. -#. Open the dataset, using the open method. -#. Reference the portion of the variable to be read. - -In the next example, a portion of variable ‘ua’ is read from dataset -‘ncep_reanalysis_mo’: - -:: - - >>> dset = db.open('ncep_reanalysis_mo') - >>> ua = dset.variables['ua'] - >>> data = ua[0,0] - - -Examples of Database Searches ------------------------------------ - -In the following examples, db is the database opened with: - -:: - - >>> db = cdms.connect() - -This defaults to the database defined in environment variable -``CDMSROOT``. - -**Example:** List all variables in dataset ‘ncep\_reanalysis\_mo’: - -:: - - >>> for entry in db.searchFilter(filter = "parentid=ncep_reanalysis_mo", tag = "variable"): - >>> print entry.name - - -**Example:** Find all axes with bounds defined: - - - -**Example:** Locate all GDT datasets: - -:: - - >>> for entry in db.searchFilter(filter="Conventions=GDT*",tag="dataset"): - >>> print entry.name - -**Example:** Find all variables with missing time values, in observed datasets: - - >>> for entry in db.searchFilter(filter = "(&(project=CMIP2)(id=hfss))", tag = "variable"): - >>> print entry.getObject().parent.id - -**Example:** Find all observed variables on 73x144 grids: - - -**Example:** Find all CMIP2 datasets having a variable with id “hfss”: - -:: - - >>> print len(db.searchFilter(tag="database")),"database" - >>> print len(db.searchFilter(tag="dataset")),"datasets" - >>> print len(db.searchFilter(tag="variable")),"variables" - >>> print len(db.searchFilter(tag="axis")),"axes" - -**Example:** Find all observed variables on 73x144 grids: - -:: - - "Dictionary", "``attributes``", "Dataset external attributes." - "Dictionary", "``axes``", "Axes contained in the dataset." - "String", "``datapath``", "Path of data files, relative to the parent database. If no parent, the datapath is absolute." - "Dictionary", "``grids``", "Grids contained in the dataset." - "String", "``mode``", "Open mode." - "Database", "``parent``", "Database which contains this dataset. If the dataset is not part of a database, the value is ``None``." - "String", "``uri``", "Uniform Resource Identifier of this dataset." - "Dictionary", "``variables``", "Variables contained in the dataset." - "Dictionary", "``xlinks``", "External links contained in the dataset." - -**Example:** Find all observed variables with more than 1000 timepoints: - -:: - - "‘r’", "read-only" - "‘r+’", "read-write" - "‘a’", "read-write. Open the file if it exists, otherwise create a new file" - "‘w’", "Create a new file, read-write" - -**Example:** Find the total number of each type of object in the database: - -:: - >>> f = cdms.open('test. xml') - >>> x = f('prc', time=('1980-1','1981-1'))" - - "Variable, Axis, or Grid", "``datasetobj['id']``", "The square bracket operator applied to a dataset gets the persistent variable, axis or grid object having the string identifier. This does not read the data for a variable. Returns ``None`` if not found. - Dataset ^^^^^^^ @@ -1276,7 +862,7 @@ See “cu Module". Dataset Internal Attributes --------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Name", "Description" :widths: 20, 30, 80 @@ -1293,7 +879,7 @@ Dataset Internal Attributes Dataset Constructors -------------------- -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 50, 80 :align: left @@ -1304,7 +890,7 @@ Dataset Constructors Open Modes ---------- -.. csv-table:: +.. csv-table:: :header: "Mode", "Definition" :widths: 50, 70 :align: left @@ -1318,7 +904,7 @@ Open Modes Dataset Methods --------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition", "Description" :widths: 30, 42, 80 @@ -1336,12 +922,12 @@ Dataset Methods >>> f = cdms.open('sampl e.xml') >>> v = f['prc'] * gets the persistent variable v, equivalent to ``v =f.variab les['prc']``. - + **Example:** - >>> t = f['time'] gets the axis named 'time', equivalent to + >>> t = f['time'] gets the axis named 'time', equivalent to >>> t = f.axes['time']" "None", "``close()``", "Close the dataset." - "RectGrid", "``createRectGrid(id, lat, lon,order, type='generic', mask=None)``", "Create a RectGrid in the dataset. + "RectGrid", "``createRectGrid(id, lat, lon,order, type='generic', mask=None)``", "Create a RectGrid in the dataset. This is not a persistent object: the order, type, and mask are not written to the dataset. However, the grid may be used for regridding operations. * ``lat`` is a latitude axis in the dataset. @@ -1349,11 +935,11 @@ Dataset Methods * ``order`` is a string with value 'yx' (the first grid dimension is latitude) or 'xy' (the first grid dimension is longitude). * ``type`` is one of 'gaussian','uniform','eq ualarea',or 'generic' * If specified, ``mask`` is a two-dimensional, logical Numpy array (all values are zero or one) with the same shape as the grid." - + Dataset Methods(Cont'd) ----------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Definition", "Description" :widths: 30, 42, 80 @@ -1431,12 +1017,12 @@ corresponding MV2 function: ``allclose``, ``allequal``, ``set_print_limit``, ``shape``, ``size``. See the documentation at http://numpy.sourceforge.net for a description of these functions. - + Variable Constructors in Module MV ----------------------------------- -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 50, 80 :align: left @@ -1458,7 +1044,7 @@ exception of argsort, all functions return a transient variable. MV Functions ------------ -.. csv-table:: +.. csv-table:: :header: "Function", "Description" :widths: 50, 80 :align: left @@ -1472,9 +1058,9 @@ MV Functions x along the selected axis. * If weights is given, it must match the size and shape of x, and the value returned is: ``sum(a*weights)/sum(weights)`` * In computing these sums, elements that correspond to those that are masked in x or weights are ignored." - "``choose(condition, t)``", "Has a result shaped like array condition. - * ``t`` must be a tuple of two arrays ``t1`` and ``t2``. - * Each element of the result is the corresponding element of ``t1``\ where ``condition`` is true, and the corresponding element of ``t2`` where ``condition`` is false. + "``choose(condition, t)``", "Has a result shaped like array condition. + * ``t`` must be a tuple of two arrays ``t1`` and ``t2``. + * Each element of the result is the corresponding element of ``t1``\ where ``condition`` is true, and the corresponding element of ``t2`` where ``condition`` is false. * The result is masked where ``condition`` is masked or where the selected element is masked." "``concatenate(arrays, axis=0, axisid=None, axisattributes=None)``", "Concatenate the arrays along the given axis. Give the extended axis the id and attributes provided - by default, those of the first array." "``count(a, axis=None)``", "Count of the non-masked elements in ``a``, or along a certain axis." @@ -1487,12 +1073,12 @@ MV Functions "``masked_not_equal(x, value)``", "``x`` masked where ``x != value``" "``masked_outside(x, v1, v2)``", "``x`` with mask of all values of ``x`` that are outside ``[v1,v2]``" "``masked_where(condition, x, copy=1)``", "Return ``x`` as a variable masked where condition is true. - * Also masked where ``x`` or ``condition`` masked. + * Also masked where ``x`` or ``condition`` masked. * ``condition`` is a masked array having the same shape as ``x``." - + MV Functions(cont'd) -------------------- -.. csv-table:: +.. csv-table:: :header: "Function", "Description" :widths: 50, 80 :align: left @@ -1504,7 +1090,7 @@ MV Functions(cont'd) "``power(a, b)``", "``a**b``" "``product(a, axis=0, fill_value=1)``", "Product of elements along axis using ``fill_value`` for missing elements." "``repeat(ar, repeats, axis=0)``", "Return ``ar`` repeated ``repeats`` times along ``axis``. ``repeats`` is a sequence of length ``ar.shape[axis]`` telling how many times to repeat each element." - "``set_default_fill_value (value_type, value)``", "Set the default fill value for ``value_type`` to ``value``. + "``set_default_fill_value (value_type, value)``", "Set the default fill value for ``value_type`` to ``value``. * ``value_type`` is a string: ‘real’,’complex’,’character’,’integer’,or ‘object’. * ``value`` should be a scalar or single-element array." "``sort(ar, axis=-1)``", "Sort array ``ar`` elementwise along the specified axis. The corresponding axis in the result has dummy values." @@ -1532,7 +1118,7 @@ CDMS supports several types of HorizontalGrids: Grids ----- -.. csv-table:: +.. csv-table:: :header: "Grid Type", "Definition" :widths: 50, 80 :align: left @@ -1544,7 +1130,7 @@ Grids HorizontalGrid Internal Attribute --------------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Name", "Definition" :widths: 30, 30, 100 :align: left @@ -1554,20 +1140,20 @@ HorizontalGrid Internal Attribute "Dataset or CdmsFile", "``parent``", "The dataset or file which contains the grid." "Tuple", "``shape``", "The shape of the grid, a 2-tuple" - + RectGrid Constructors --------------------- -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 30, 80 :align: left - "``cdms.createRectGrid(lat, lon, order, type='generic', mask=None)``", "Create a grid not associated with a file or dataset. See `A First Example`_" + "``cdms.createRectGrid(lat, lon, order, type='generic', mask=None)``", "Create a grid not associated with a file or dataset. See `A First Example`_" "``CdmsFile.createRectGrid(id, lat, lon, order, type='generic', mask=None)``", "Create a grid associated with a file. See `CdmsFile Constructors <#table-cdmsfile-constructors>`_" - "``Dataset.createRectGrid(id, lat, lon, order, type='generic', mask=None)``", "Create a grid associated with a dataset. See `Dataset Constructors <#table-dataset-constructors>`_ " + "``Dataset.createRectGrid(id, lat, lon, order, type='generic', mask=None)``", "Create a grid associated with a dataset. See `Dataset Constructors <#table-dataset-constructors>`_ " "``cdms.createGaussianGrid (nlats, xorigin=0.0, order='yx')``", "See `A First Example`_" "``cdms.createGenericGrid (latArray, lonArray, latBounds=None, lonBounds=None, order='yx', mask=None)``", "See `A First Example`_" "``cdms.createGlobalMeanGrid (grid)``", "See `A First Example`_" @@ -1581,7 +1167,7 @@ HorizontalGrid Methods ---------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Description" :widths: 30, 30, 80 @@ -1597,43 +1183,43 @@ HorizontalGrid Methods * For generic grids with shape (ncell,), the boundary arrays each have shape (ncell, nvert) where nvert is the maximum number of vertices per cell. * For rectilinear grids: If no boundary arrays are explicitly defined (in the file or dataset), the result depends on the auto- Bounds mode (see ``cdms.setAutoBounds``) and the grid classification mode (see ``cdms.setClassifyGrids``). By default, autoBounds mode is enabled, in which - case the boundary arrays are generated based on - the type of grid. + case the boundary arrays are generated based on + the type of grid. * If disabled, the return value is (None,None).For rectilinear grids: - * The grid classification mode specifies how the grid type is to be determined. - * By default, the grid type (Gaussian, uniform, etc.) is determined by calling grid.classifyInFamily. + * The grid classification mode specifies how the grid type is to be determined. + * By default, the grid type (Gaussian, uniform, etc.) is determined by calling grid.classifyInFamily. * If the mode is 'off' grid.getType is used instead." "Axis", "``getLatitude()``", "Get the latitude axis of this grid." "Axis", "``getLongitude()``", "Get the latitude axis of this grid." - + HorizontalGrid Methods(cont'd) ------------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Description" :widths: 30, 30, 80 "Axis", "``getMask()``", "Get the mask array of this grid, if any. - * Returns a 2-D Numpy array, having the same shape as the grid. + * Returns a 2-D Numpy array, having the same shape as the grid. * If the mask is not explicitly defined, the return value is ``None``." "Axis", "``getMesh(self, transpose=None)``", "Generate a mesh array for the meshfill graphics method. * If transpose is defined to a tuple, say (1,0), first transpose latbounds and lonbounds according to the tuple, in this case (1,0,2)." - "None", "``setBounds (latBounds, lonBounds, persistent=0)``", "Set the grid boundaries. - * ``latBounds`` is a NumPy array of shape (n,2), such that the boundaries of the kth axis value are ``[latBounds[k,0],latBou nds[k,1] ]``. + "None", "``setBounds (latBounds, lonBounds, persistent=0)``", "Set the grid boundaries. + * ``latBounds`` is a NumPy array of shape (n,2), such that the boundaries of the kth axis value are ``[latBounds[k,0],latBou nds[k,1] ]``. * ``lonBounds`` is defined similarly for the longitude array. **Note:** By default, the boundaries are not written to the file or dataset containing the grid (if any). This allows bounds to be set on read-only files, for regridding. If the optional argument ``persistent`` is set to the boundary array is written to the file." "None", "``setMask(mask, persistent=0)``", "Set the grid mask. - * If ``persistent == 1``, the mask values are written to the associated file, if any. - * Otherwise, the mask is associated with the grid, but no I/O is generated. + * If ``persistent == 1``, the mask values are written to the associated file, if any. + * Otherwise, the mask is associated with the grid, but no I/O is generated. * ``mask`` is a two-dimensional, Boolean-valued Numpy array, having the same shape as the grid." HorizontalGrid Methods(cont'd) ------------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Description" :widths: 30, 30, 80 @@ -1649,41 +1235,41 @@ HorizontalGrid Methods(cont'd) Where ``x`` and ``y`` are coordinates indicating the interval ``[x,y)``, and: * ``indicator`` is a two-character string, where the first character is 'c' if the interval is closed on the left, 'o' if open, and the second character has the same meaning for the right-hand point. (Default: 'co'). - * If ``cycle`` is specified, the axis is treated as circular with the given cycle value. + * If ``cycle`` is specified, the axis is treated as circular with the given cycle value. * By default, if ``grid.isCircular()`` is true, the axis is treated as circular with a default value of 360.0. * An interval of ``None`` returns the full index interval of the axis. * If a mask is defined, the subgrid also has a mask corresponding to the index ranges. **Note:** The result grid is not associated with any file or dataset." - "Transient-CurveGrid", "``toCurveGrid (gridid=None)``", "Convert to a curvilinear grid. - * If the grid is already curvilinear, a copy of the grid object is returned. - * ``gridid`` is the string identifier of the resulting curvilinear grid object. + "Transient-CurveGrid", "``toCurveGrid (gridid=None)``", "Convert to a curvilinear grid. + * If the grid is already curvilinear, a copy of the grid object is returned. + * ``gridid`` is the string identifier of the resulting curvilinear grid object. * If unspecified, the grid ID is copied. - **Note:** This method does not apply to generic grids. + **Note:** This method does not apply to generic grids. * Transient-GenericGrid ``toGenericGrid(gridid=None)`` Convert to a generic grid. - * If the grid is already generic, a copy of the grid is returned. + * If the grid is already generic, a copy of the grid is returned. * ``gridid`` is the string identifier of the resulting curvilinear grid object. - * If unspecified, the grid ID is copied." + * If unspecified, the grid ID is copied." RectGrid Methods, Additional to HorizontalGrid Methods ------------------------------------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Description" :widths: 30, 30, 80 "String", "``getOrder()``", "Get the grid ordering, either 'yx' if latitude is the first axis, - or 'xy' if longitude is the first axis. - String ``getType()`` - * Get the grid type, either 'gaussian', 'uniform', 'equalarea', or 'generic'. - * (Array,Array) ``getWeights()`` + or 'xy' if longitude is the first axis. + String ``getType()`` + * Get the grid type, either 'gaussian', 'uniform', 'equalarea', or 'generic'. + * (Array,Array) ``getWeights()`` * Get the normalized area weight arrays, as a tuple ``(latWeights, lonWeights)``. * It is assumed that the latitude and longitude axes are defined in degrees. The latitude weights are defined as: * ``latWeights[i] = 0.5 * abs(sin(latBounds[i+1]) - sin(latBounds[i]))`` The longitude weights are defined as: * ``lonWeights[i] = abs(lonBounds[i+1] - lonBounds [i])/360.0`` - For a global grid, the weight arrays are normalized + For a global grid, the weight arrays are normalized such that the sum of the weights is 1.0 **Example:** * Generate the 2-D weights array, such that ``weights[i.j]`` is the fractional area of grid zone ``[i,j]``. @@ -1691,13 +1277,13 @@ RectGrid Methods, Additional to HorizontalGrid Methods * latwts, lonwts = gri d.getWeights() * weights = MV.outerproduct(latwts, lonwts) * Also see the function ``area_weights`` in module ``pcmdi.weighting``." - "None", "``setType (gridtype)``", "Set the grid type. + "None", "``setType (gridtype)``", "Set the grid type. * ``gridtype`` is one of 'gaussian', 'uniform', 'equalarea', or 'generic'." RectGrid Methods, Additional to HorizontalGrid Methods(cont'd) ------------------------------------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Description" :widths: 30, 30, 80 @@ -1743,7 +1329,7 @@ variable. Variable Internal Attributes ---------------------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Name", "Definition" :widths: 30, 30, 80 @@ -1757,7 +1343,7 @@ Variable Internal Attributes Variable Constructors --------------------- -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 30, 80 :align: left @@ -1765,20 +1351,20 @@ Variable Constructors "``Dataset.createVariable (String id, String datatype, List axes)``", "Create a Variable in a Dataset. This function is not yet implemented." "``CdmsFile.createVariable (String id, String datatype, List axes or Grids)``", "Create a Variable in a CdmsFile. - * ``id`` is the name of the variable. - * ``datatype`` is the MV2 or Numpy | typecode, for example, MV2.Float. - * ``axesOrGrids`` is a list of Axis and/or Grid objects, on which the variable is defined. Specifying a rectilinear grid is equivalent to listing the grid latitude and longitude axes, in the order defined for the grid. + * ``id`` is the name of the variable. + * ``datatype`` is the MV2 or Numpy | typecode, for example, MV2.Float. + * ``axesOrGrids`` is a list of Axis and/or Grid objects, on which the variable is defined. Specifying a rectilinear grid is equivalent to listing the grid latitude and longitude axes, in the order defined for the grid. **Note:** This argument can either be a list or a tuple. If the tuple form is used, and there is only one element, it must have a following comma, e.g.: ``(axisobj,)``." - "``cdms.createVariable (array, typecode=None, copy=0, savespace=0,mask=None, fill_value=None, grid=None, axes=None,attributes=None, id=None)``", "Create a transient variable, not associated with a file or dataset. + "``cdms.createVariable (array, typecode=None, copy=0, savespace=0,mask=None, fill_value=None, grid=None, axes=None,attributes=None, id=None)``", "Create a transient variable, not associated with a file or dataset. * ``array`` is the data values: a Variable, masked array, or Numpy array. - * ``typecode`` is the MV2 typecode of the array. Defaults to the typecode of array. - * ``copy`` is an integer flag: if 1, the variable is created with a copy of the array, if 0 the variable data is shared with array. - * ``savespace`` is an integer flag: if set to 1, internal Numpy operations will attempt to avoid silent upcasting. - * ``mask`` is an array of integers with value 0 or 1, having the same shape as array. array elements with a corresponding mask value of 1 are considered invalid, and are not used for subsequent Numpy operations. The default mask is obtained from array if present, otherwise is None. - * ``fill_value`` is the missing value flag. The default is obtained from array if possible, otherwise is set to 1.0e20 for floating point variables, 0 for integer-valued variables. + * ``typecode`` is the MV2 typecode of the array. Defaults to the typecode of array. + * ``copy`` is an integer flag: if 1, the variable is created with a copy of the array, if 0 the variable data is shared with array. + * ``savespace`` is an integer flag: if set to 1, internal Numpy operations will attempt to avoid silent upcasting. + * ``mask`` is an array of integers with value 0 or 1, having the same shape as array. array elements with a corresponding mask value of 1 are considered invalid, and are not used for subsequent Numpy operations. The default mask is obtained from array if present, otherwise is None. + * ``fill_value`` is the missing value flag. The default is obtained from array if possible, otherwise is set to 1.0e20 for floating point variables, 0 for integer-valued variables. * ``grid`` is a rectilinear grid object. - * ``axes`` is a tuple of axis objects. By default the axes are obtained from array if present. Otherwise for a dimension of length n, the default axis has values [0., 1., ..., double(n)]. - * ``attributes`` is a dictionary of attribute values. The dictionary keys must be strings. By default the dictionary is obtained from array if present, otherwise is empty. + * ``axes`` is a tuple of axis objects. By default the axes are obtained from array if present. Otherwise for a dimension of length n, the default axis has values [0., 1., ..., double(n)]. + * ``attributes`` is a dictionary of attribute values. The dictionary keys must be strings. By default the dictionary is obtained from array if present, otherwise is empty. * ``id`` is the string identifier of the variable. By default the id is obtained from array if possible, otherwise is set to 'variable\_n' for some integer." @@ -1786,34 +1372,34 @@ Variable Constructors Variable Methods ---------------- -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left "Variable", "``tvar = var[ i:j, m:n]``", "Read a slice of data from the file or dataset, resulting - in a transient variable. - * Singleton dimensions are 'squeezed' out. - * Data is returned in the physical ordering defined in the dataset. + in a transient variable. + * Singleton dimensions are 'squeezed' out. + * Data is returned in the physical ordering defined in the dataset. * The forms of the slice operator are listed in `Variable Slice Operators <#table-variable-slice-operators>`_" - "None", "``var[ i:j, m:n] = array``", "Write a slice of data to the external dataset. + "None", "``var[ i:j, m:n] = array``", "Write a slice of data to the external dataset. * The forms of the slice operator are listed in `Result Entry Methods <#table-resultentry-methods>`_ . (Variables in CdmsFiles only)" - "Variable", "``tvar = var(selector)``", "Calling a variable as a function reads the region of - data defined by the selector. - * The result is a transient variable, unless raw=1 keyword is specified. + "Variable", "``tvar = var(selector)``", "Calling a variable as a function reads the region of + data defined by the selector. + * The result is a transient variable, unless raw=1 keyword is specified. * See `Selectors' <#selectors>`_ ." "None", "``assignValue(Array ar)``", "Write the entire data array. Equivalent to ``var[:] = ar``. (Variables in CdmsFiles only)." "Variable", "``astype(typecode)``", "Cast the variable to a new datatype. * Typecodes are as for MV, MV2, and Numpy modules." "Variable", "``clone(copyData=1)``", "Return a copy of a transient variable. - * If copyData is 1 (the default) the variable data is copied as well. + * If copyData is 1 (the default) the variable data is copied as well. * If copyData is 0, the result transient variable shares the original transient variables data array." Variable Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 45, 80 :align: left @@ -1821,7 +1407,7 @@ Variable Methods(cont'd) "Transient Variable", "``crossSectionRegrid (newLevel, newLatitude, method='log', missing=None, order=None)``", "Return a lat/level vertical cross-section regridded to a new set of - latitudes newLatitude and levels newLevel. + latitudes newLatitude and levels newLevel. * The variable should be a function of latitude, level, and (optionally) time. * ``newLevel`` is an axis of the result pressure levels. * ``newLatitude`` is an axis of the result latitudes. @@ -1839,13 +1425,13 @@ Variable Methods(cont'd) of the variable. * If ``axes`` is not ``None``, include only certain axes. Otherwise axes is a list of specifications as described below. Axes are returned in the order specified unless the order keyword is given. - * If ``omit`` is not ``None``, omit those specified by an integer dimension number. Otherwise omit is a list of specifications as described below. + * If ``omit`` is not ``None``, omit those specified by an integer dimension number. Otherwise omit is a list of specifications as described below. * ``order`` is an optional string determining the output order." Variable Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left @@ -1859,7 +1445,7 @@ Variable Methods(cont'd) * ``order`` can be a string containing the characters t,x,y,z, or * . * If a dash ('-') is given, any elements of the result not chosen otherwise are filled in from left to right with remaining candidates." "List", "``getAxisListIndex (axes=None, omit=None, order=None)``", "Return a list of indices of axis objects. Arguments are as for getAxisList." - "List", "``getDomain()``", "Get the domain. + "List", "``getDomain()``", "Get the domain. Each element of the list is itself a tuple of the form ``(axis,start,length,tru e_length)`` * Where axis is an axis object, @@ -1874,16 +1460,16 @@ Variable Methods(cont'd) Variable Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left "Various", "``getMissing()``", "Get the missing data value, or ``None`` if not found." - "String","``getOrder()``", "Get the order string of a spatio-temporal variable. - * The order string specifies the physical ordering of the data. - * It is a string of characters with length equal to the rank of the variable, indicating the order of the variable's time, level, latitude, - and/or longitude axes. + "String","``getOrder()``", "Get the order string of a spatio-temporal variable. + * The order string specifies the physical ordering of the data. + * It is a string of characters with length equal to the rank of the variable, indicating the order of the variable's time, level, latitude, + and/or longitude axes. Each character is one of: * 't': time * 'z': vertical level @@ -1893,7 +1479,7 @@ Variable Methods(cont'd) **Example:** A variable with ordering 'tzyx' is 4-dimensional, where the ordering of axes is (time, level, latitude, longitude). **Note:** The order string is of the form required for the order argument of a regridder function. - * ``intervals`` is a list of scalars, 2-tuples representing [i,j), slices, and/or Ellipses. + * ``intervals`` is a list of scalars, 2-tuples representing [i,j), slices, and/or Ellipses. * If no ``argument(s)`` are present, all file paths associated with the variable are returned. * Returns a list of tuples of the form (path,slicetuple), where path is the path of a file, and slicetuple is itself a tuple of slices, of the same length as the rank of the variable, representing the portion of the variable in the file corresponding to intervals. **Note:** This function is not defined for transient various." @@ -1903,17 +1489,17 @@ Variable Methods(cont'd) Variable Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left "Integer", "``len(var)``", "The length of the first dimension of the variable. - If the variable is zero-dimensional (scalar), a length + If the variable is zero-dimensional (scalar), a length of 0 is returned. **Note:** ``size()`` returns the total number of elements." - "Transient Variable", "``pressureRegrid (newLevel, method='log', missin=None, order=None)``", "Return the variable regridded to a new set of + "Transient Variable", "``pressureRegrid (newLevel, method='log', missin=None, order=None)``", "Return the variable regridded to a new set of pressure levels newLevel. The variable must be a function of latitude, longitude, pressure level, and (optionally) time. * ``newLevel`` is an axis of the result pressure levels. @@ -1925,25 +1511,25 @@ Variable Methods(cont'd) "Transient", "``regrid (togrid, missing=None, order=None, Variable mask=None)``","Return the variable regridded to the horizontal grid togrid. * ``missing`` is a Float specifying the missing data value. The default is 1.0e20. - * ``order`` is a string indicating the order of dimensions of the array. It has the form returned from ``variable.getOrder()``. - * For example, the string 'tzyx' indicates that the dimension order of array is (time, level, latitude, longitude). + * ``order`` is a string indicating the order of dimensions of the array. It has the form returned from ``variable.getOrder()``. + * For example, the string 'tzyx' indicates that the dimension order of array is (time, level, latitude, longitude). * If unspecified, the function assumes that the last two dimensions of array match the input grid. - * ``mask`` is a Numpy array, of datatype Integer or Float, consisting of ones and zeros. A value of 0 or 0.0 indicates that the corresponding - data value is to be ignored for purposes of regridding. + * ``mask`` is a Numpy array, of datatype Integer or Float, consisting of ones and zeros. A value of 0 or 0.0 indicates that the corresponding + data value is to be ignored for purposes of regridding. * If mask is two-dimensional of the same shape as the input grid, it overrides the mask of the input grid." Variable Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left "Transient(cont'd)", "``regrid (togrid, missing=None, order=None, Variable mask=None)``","Return the variable regridded to the horizontal - grid togrid. - * If the mask has more than two dimensions, it must have the same shape as array. In this case, the missing data value is also ignored. - * Such an n-dimensional mask is useful if the pattern of missing data varies with level (e.g., ocean data) or time. + grid togrid. + * If the mask has more than two dimensions, it must have the same shape as array. In this case, the missing data value is also ignored. + * Such an n-dimensional mask is useful if the pattern of missing data varies with level (e.g., ocean data) or time. **Note:** If neither missing or mask is set, the default mask is obtained from the mask of the array if any. See also: ``crossSectionRegrid``, ``pressureRegrid``." @@ -1954,16 +1540,16 @@ Variable Methods(cont'd) transient variable. A region is a hyperrectangle in coordinate space. * ``region`` is an argument list, each item of which specifies an interval of a coordinate axis. The intervals are listed in the order of the variable axes. - * If trailing dimensions are omitted, all values of those dimensions are retrieved. + * If trailing dimensions are omitted, all values of those dimensions are retrieved. * If an axis is circular (axis.isCircular() is true) or cycle is specified (see below), then data will be read with wraparound in that dimension. * Only one axis may be read with wraparound. - * A coordinate interval has one of the forms listed in `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ . + * A coordinate interval has one of the forms listed in `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ . * Also see ``axis.mapIntervalExt``." Variable Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left @@ -1972,26 +1558,26 @@ Variable Methods(cont'd) transient variable. A region is a hyperrectangle in coordinate space. * The optional keyword arguments ``time``, ``level``, ``latitude``, and ``longitude`` may also be used to specify the dimension for which the interval applies. - This is particularly useful if the order of dimensions is not known in advance. + This is particularly useful if the order of dimensions is not known in advance. * An exception is raised if a keyword argument conflicts with a positional region argument. - * The optional keyword argument ``squeeze`` determines whether or not the shape of the returned array contains dimensions whose length is 1; by default this + * The optional keyword argument ``squeeze`` determines whether or not the shape of the returned array contains dimensions whose length is 1; by default this argument is 0, and such dimensions are not 'squeezed out'. - * The optional keyword argument ``raw`` specifies whether the return object is a variable or a masked array. + * The optional keyword argument ``raw`` specifies whether the return object is a variable or a masked array. * By default, a transient variable is returned, having the axes and attributes corresponding to2,3 the region read. If raw=1, an MV2 masked array is returned, equivalent to the transient variable without the axis and attribute information." Variable Methods(cont'd) ------------------------ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 30, 42, 80 :align: left - "Variable", "``subSlice (*specs, time=None, level=None, latitude=None, longitude=None, squeeze=0, raw=0)``", "Read a slice of data, returning a transient variable. - This is a functional form of the slice operator [] + "Variable", "``subSlice (*specs, time=None, level=None, latitude=None, longitude=None, squeeze=0, raw=0)``", "Read a slice of data, returning a transient variable. + This is a functional form of the slice operator [] with the squeeze option turned off. - * ``specs`` is an argument list, each element of which specifies a slice of the corresponding dimension. + * ``specs`` is an argument list, each element of which specifies a slice of the corresponding dimension. There can be zero or more positional arguments, each of the form: * A single integer n, meaning ``slice(n, n+1)`` @@ -2035,7 +1621,7 @@ Read all data for March, 1980: Variable Slice Operators ------------------------ -.. csv-table:: +.. csv-table:: :header: "Operator", "Description" :widths: 30, 80 @@ -2054,7 +1640,7 @@ Variable Slice Operators Index and Coordinate Intervals ------------------------------ -.. csv-table:: +.. csv-table:: :header: "Interval Definition", "Example Interval Definition", "Example" :widths: 30, 80, 80 @@ -2139,7 +1725,7 @@ to the axis order of a variable. For example: Selector Keywords ----------------- -.. csv-table:: +.. csv-table:: :header: "Keyword", "Description", "Value" :widths: 30, 80, 80 @@ -2152,7 +1738,7 @@ Selector Keywords "raw", "Return a masked array (MV2.array) rather than a transient variable.", "0: return a transient variable (default); =1: return a masked array." "required", "Require that the axis IDs be present.", "List of axis identifiers." "squeeze", "Remove singleton dimensions from the result.", "0: leave singleton dimensions (default); 1: remove singleton dimensions." - "time", "Restrict time values to a value or range.", See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ + "time", "Restrict time values to a value or range.", See `Index and Coordinate Intervals <#table-index-and-coordinate-intervals>`_ Another form of selector components is the positional form, where the component order corresponds to the axis order of a variable. For @@ -2177,7 +1763,7 @@ takes an argument list of selector components. For example: :: - + >>> from cdms.selectors import Selector >>> sel = Selector(time=('1979-1-1','1979-2-1'), level=1000.) >>> x1 = v1(sel) @@ -2262,46 +1848,46 @@ remove the singleton level dimension from the result array. >>> import cdms >>> f = cdms.open('sample.nc') >>> hus = f.variables['hus'] - >>> + >>> >>> # Keyword selection >>> x = hus(time=('1979-1-1','1979-2-1'), level=1000.) - >>> + >>> >>> # Interval indicator (see mapIntervalExt) >>> x = hus(time=('1979-1-1','1979-3-1','co'), level=1000.) - >>> + >>> >>> # Axis ID (plev) as a keyword >>> x = hus(time=('1979-1-1','1979-2-1'), plev=1000.) - >>> + >>> >>> # Positional >>> x9 = hus(('1979-1-1','1979-2-1'),1000.0) - >>> + >>> >>> # Predefined selectors >>> from cdms import time, level >>> x = hus(time('1979-1-1','1979-2-1'), level(1000.)) - >>> + >>> >>> from cdms import timeslice, levelslice >>> x = hus(timeslice(0,2), levelslice(16,17)) - >>> + >>> >>> # Call file as a function >>> x = f('hus', time=('1979-1-1','1979-2-1'), level=1000.) - >>> + >>> >>> # Python slices >>> x = hus(time=slice(0,2), level=slice(16,17)) - >>> + >>> >>> # Selector objects >>> from cdms.selectors import Selector >>> sel = Selector(time=('1979-1-1','1979-2-1'), level=1000.) >>> x = hus(sel) - >>> + >>> >>> sel2 = Selector(time=('1979-1-1','1979-2-1')) >>> sel3 = sel2 & level(1000.0) >>> x = hus(sel3) >>> x = hus(sel2, level=1000.0) - >>> + >>> >>> # Squeeze singleton dimension (level) >>> x = hus[0:2,16] >>> x = hus(time=('1979-1-1','1979-2-1'), level=1000., squeeze=1) - >>> + >>> >>> f.close() @@ -2329,45 +1915,45 @@ results are written to a netCDF file. For brevity, the functions >>> 1. import cdms >>> import MV - >>> - >>> # Calculate variance, slope, and correlation of + >>> + >>> # Calculate variance, slope, and correlation of >>> # surface air temperature with upper air temperature >>> # by level, and save to a netCDF file. 'pathTa' is the location of >>> # the file containing 'ta', 'pathTas' is the file with contains 'tas'. >>> # Data is extracted from January of year1 through December of year2. >>> def ccSlopeVarianceBySeasonFiltNet(pathTa,pathTas,month1,month2): - >>> + >>> >>> # Open the files for ta and tas >>> fta = cdms.open(pathTa) >>> ftas = cdms.open(pathTas) - >>> + >>> >>> 2. #Get upper air temperature >>> taObj = fta['ta'] >>> levs = taObj.getLevel() - >>> + >>> >>> #Get the surface temperature for the closed interval [time1,time2] >>> tas = ftas('tas', time=(month1,month2,'cc')) - >>> + >>> >>> # Allocate result arrays >>> newaxes = taObj.getAxisList(omit='time') >>> newshape = tuple([len(a) for a in newaxes]) >>> cc = MV.zeros(newshape, typecode=MV.Float, axes=newaxes, id='correlation') >>> b = MV.zeros(newshape, typecode=MV.Float, axes=newaxes, id='slope') >>> v = MV.zeros(newshape, typecode=MV.Float, axes=newaxes, id='variance') - >>> + >>> >>> # Remove seasonal cycle from surface air temperature >>> tas = removeSeasonalCycle(tas) - >>> + >>> >>> # For each level of air temperature, remove seasonal cycle >>> # from upper air temperature, and calculate statistics >>> 5. for ilev in range(len(levs)): - >>> + >>> >>> ta = taObj(time=(month1,month2,'cc'), \ >>> level=slice(ilev, ilev+1), squeeze=1) - >>> ta = removeSeasonalCycle(ta) + >>> ta = removeSeasonalCycle(ta) >>> cc[ilev], b[ilev] = corrCoefSlope(tas ,ta) >>> v[ilev] = MV.sum( ta**2 )/(1.0*ta.shape[0]) - >>> + >>> >>> # Write slope, correlation, and variance variables >>> 6. f = cdms.open('CC_B_V_ALL.nc','w') >>> f.title = filtered @@ -2375,10 +1961,10 @@ results are written to a netCDF file. For brevity, the functions >>> f.write(cc) >>> f.write(v) >>> f.close() - >>> + >>> >>> 7. if __name__=='__main__': >>> pathTa = '/pcmdi/cdms/sample/ccmSample_ta.xml' - >>> pathTas = '/pcmdi/cdms/sample/ccmSample_tas.xml' + >>> pathTas = '/pcmdi/cdms/sample/ccmSample_tas.xml' >>> # Process Jan80 through Dec81 >>> ccSlopeVarianceBySeasonFiltNet(pathTa,pathTas,'80-1','81-12') @@ -2420,16 +2006,16 @@ the vcs module. >>> # Calculates gridpoint total variance >>> # from an array of interest >>> # - >>> + >>> >>> import cdms >>> from MV import * - >>> + >>> >>> # Wait for return in an interactive window - >>> + >>> >>> def pause(): >>> print Hit return to continue: , >>> line = sys.stdin.readline() - >>> + >>> >>> 1. # Calculate pointwise variance of variable over time >>> # Returns the variance and the number of points >>> # for which the data is defined, for each grid point @@ -2438,30 +2024,30 @@ the vcs module. >>> firstaxis = x.getAxis(0) >>> if not firstaxis.isTime(): >>> raise 'First axis is not time, variable:', x.id - >>> + >>> >>> n = count(x,0) >>> sumxx = sum(x*x) >>> sumx = sum(x) >>> variance = (n*sumxx -(sumx * sumx))/(n * (n-1.)) - >>> + >>> >>> return variance, n - >>> + >>> >>> if __name__=='__main__': >>> import vcs, sys - >>> + >>> >>> print 'Enter dataset path [/pcmdi/cdms/obs/erbs_mo.xml]: ', >>> path = string.strip(sys.stdin.readline()) >>> if path=='': path='/pcmdi/cdms/obs/erbs_mo.xml' - >>> + >>> >>> 2. # Open the dataset >>> dataset = cdms.open(path) - >>> + >>> >>> # Select a variable from the dataset >>> print 'Variables in file:',path >>> varnames = dataset.variables.keys() >>> varnames.sort() >>> for varname in varnames: - >>> + >>> >>> var = dataset.variables[varname] >>> if hasattr(var,'long_name'): >>> long_name = var.long_name @@ -2469,20 +2055,20 @@ the vcs module. >>> long_name = var.title >>> else: >>> long_name = '?' - >>> + >>> >>> print '%-10s: %s'%(varname,long_name) >>> print 'Select a variable: ', >>> 3. varname = string.strip(sys.stdin.readline()) >>> var = dataset(varname) >>> dataset.close() - >>> + >>> >>> # Calculate variance, count, and set attributes >>> variance,n = calcVar(var) >>> variance.id = 'variance_%s'%var.id >>> n.id = 'count_%s'%var.id >>> if hasattr(var,'units'): >>> variance.units = '(%s)^2'%var.units - >>> + >>> >>> # Plot variance >>> w=vcs.init() >>> 4. w.plot(variance) @@ -2499,7 +2085,7 @@ The result of running this script is as follows: >>> % calcVar.py >>> Enter dataset path [/pcmdi/cdms/sample/obs/erbs_mo.xml]: - >>> + >>> >>> Variables in file: /pcmdi/cdms/sample/obs/erbs_mo.xml >>> albt : Albedo TOA [%] >>> albtcs : Albedo TOA clear sky [%] @@ -2511,11 +2097,11 @@ The result of running this script is as follows: >>> rsut : SW radiation upward TOA [W/m^2] >>> rsutcs : SW radiation upward TOA clear sky [W/m^2] >>> Select a variable: albt - >>> + >>> >>> - >>> + >>> >>> Hit return to continue: - >>> + >>> >>> diff --git a/docs/source/manual/cdms_3.rst b/docs/source/manual/cdms_3.rst index 0b7dcaa7..822ef3cf 100644 --- a/docs/source/manual/cdms_3.rst +++ b/docs/source/manual/cdms_3.rst @@ -26,7 +26,7 @@ Time Types The ``cdtime`` module implements the CDMS time types, methods, and calendars. These are made available with the command: -.. doctest:: +:: >>> import cdtime @@ -77,11 +77,11 @@ Time Constructors ^^^^^^^^^^^^^^^^^ The following table describes the methods for creating time types. - + Time Constructors ~~~~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Type", "Constructor", "Defintion" :widths: 10, 40, 80 :align: left @@ -103,7 +103,7 @@ A component time type has six members, all of which are settable. Component Time ~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Type", "Name", "Summary" :widths: 15, 15, 50 @@ -121,113 +121,113 @@ The following methods apply both to relative and component times. Time Methods ~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 35, 42, 80 :align: left - "Comptime or Reltime", "``t.add(value,intervalUnits, cdtime.DefaultCalendar)``", "Add an interval of time to a time type t. + "Comptime or Reltime", "``t.add(value,intervalUnits, cdtime.DefaultCalendar)``", "Add an interval of time to a time type t. Returns the same type of time. * ``value`` is the Float number of interval units. * ``intervalUnits`` is ``cdtime. * [Second (s) | Minute(s) Hour(s) | Day(s) | Week(s) | Month(s) | Season(s) | Year(s) ]`` * ``calendar`` is the calendar type." - "Integer", "``t.cmp(t2, cdtime.DefaultCalendar)``", "Compare time values t and t2. + "Integer", "``t.cmp(t2, cdtime.DefaultCalendar)``", "Compare time values t and t2. Returns -1, 0, 1 as t is less than, equal to, or greater than t2 respectively. * ``t2`` is the time to compare. * ``calendar`` is the calendar type." - "Comptime or Reltime", "``t.sub(value,intervalUnits, cdtime.DefaultCalendar)``", "Subtract an interval of time from a time type t. + "Comptime or Reltime", "``t.sub(value,intervalUnits, cdtime.DefaultCalendar)``", "Subtract an interval of time from a time type t. Returns the same type of time. * ``value`` is the Float number of interval units. * ``intervalUnits`` is cdtime.[Second (s) | Minute(s) | Hour(s) | Day(s) | Week(s) | Month(s) | Season(s) | Year(s)] * ``calendar`` is the calendar type. " - "Comptime", "``t.tocomp(cdtime.DefaultCalendar)``", "Convert to component time. + "Comptime", "``t.tocomp(cdtime.DefaultCalendar)``", "Convert to component time. Returns the equivalent component time. * ``calendar`` is the calendar type." - "Reltime", "``t.torel(units, cdtime.DefaultCalendar)``", "Convert to relative time. + "Reltime", "``t.torel(units, cdtime.DefaultCalendar)``", "Convert to relative time. Returns the equivalent relative time." - + Examples ^^^^^^^^ -:: + +:: >>> import cdtime >>> c = cdtime.comptime(1996,2,28) - >>> r = cdtime.reltime(28,"days since 1996-1-1") + >>> r = cdtime.reltime(28,"days since 1996-1-1") >>> print r.add(1, cdtime.Day) 29.000000 days since 1996-1-1 >>> print c.add(36, cdtime.Hours) - 1996-2-29 12:0:0.0 + 1996-2-29 12:0:0.0 **Note:** When adding or subtracting intervals of months or years, only the month and year of the result are significant. The reason is that intervals in months/years are not commensurate with intervals in days or fractional days. This leads to results that may be surprising. -.. +:: + + >>> c = comptime(1979,8,31) + >>> c.add(1, cdtime.Month) + 1979-9-1 0:0:0.0 + - >>> c = comptime(1979,8,31) - >>> c.add(1, cdtime.Month) - 1979-9-1 0:0:0.0 - +In other words, the day component of c was ignored in the addition, and the day/hour/minute components of the results are just the defaults. If the interval is in years, the interval is converted internally to months: -In other words, the day component of c was ignored in the addition, and the day/hour/minute components of the results are just the defaults. If the interval is in years, the interval is converted internally to months: - -.. +:: - >>> c = comptime(1979,8,31) - >>> c.add(2, cdtime.Years) - 1981-8-1 0:0:0.0 + >>> c = comptime(1979,8,31) + >>> c.add(2, cdtime.Years) + 1981-8-1 0:0:0.0 Compare time values. - -.. - >>> import cdtime - >>> r = cdtime.reltime(28,"days since 1996-1-1") - >>> c = cdtime.comptime(1996,2,28) - >>> print c.cmp(r) +:: + + >>> import cdtime + >>> r = cdtime.reltime(28,"days since 1996-1-1") + >>> c = cdtime.comptime(1996,2,28) + >>> print c.cmp(r) + 1 + >>> print r.cmp(c) + -1 + >>> print r.cmp(r) 1 -.. >>> print r.cmp(c) -.. -1 -.. >>> print r.cmp(r) -.. 1 - Subtract an interval of time. -.. +:: >>> import cdtime - >>> r = cdtime.reltime(28, "days since 1996-1-1") - >>> c = cdtime.comptime(1996, 2, 28) - >>> print r.sub(10, cdtime.Days) - 18.000000 days since 1996-1-1 - >>> print c.sub(30, cditme.Days) - 1996-1-29 0:0:0.0 - - + >>> r = cdtime.reltime(28, "days since 1996-1-1") + >>> c = cdtime.comptime(1996, 2, 28) + >>> print r.sub(10, cdtime.Days) + 18.000000 days since 1996-1-1 + >>> print c.sub(30, cditme.Days) + 1996-1-29 0:0:0.0 + + For intervals of years or months, see the **note** under add() in the example above. Convert to component time. -.. +:: - >>> r = cdtime.reltime(28,"days since 1996-1-1") + >>> r = cdtime.reltime(28,"days since 1996-1-1") >>> r.tocomp() - 1996-1-29 0:0:0.0 + 1996-1-29 0:0:0.0 Convert to relative time. -.. - - >>> c = comptime(1996,2,28) - >>> print c.torel("days since 1996-1-1") - 58.000000 days since 1996-1-1 - >>> r = reltime(28,"days since 1996-1-1") - >>> print r.torel("days since 1995") - 393.000000 days since 1995 - >>> print r.torel("days since 1995").value - 393.0 +:: + + >>> c = comptime(1996,2,28) + >>> print c.torel("days since 1996-1-1") + 58.000000 days since 1996-1-1 + >>> r = reltime(28,"days since 1996-1-1") + >>> print r.torel("days since 1995") + 393.000000 days since 1995 + >>> print r.torel("days since 1995").value + 393.0 diff --git a/docs/source/manual/cdms_4.rst b/docs/source/manual/cdms_4.rst index a4536ef0..6734ce64 100644 --- a/docs/source/manual/cdms_4.rst +++ b/docs/source/manual/cdms_4.rst @@ -116,7 +116,7 @@ SCRIP Horizontal Regridder To interpolate between grids where one or both grids is non-rectangular, CDMS provides an interface to the SCRIP regridder package developed at -Los Alamos National Laboratory (https://oceans11.lanl.gov/trac/SCRIP). +Los Alamos National Laboratory (https://oceans11.lanl.gov/trac/SCRIP). Figure 3 illustrates the process: @@ -159,12 +159,12 @@ In this example: >>> &remap_inputs >>> num_maps = 1 - >>> + >>> >>> grid1_file = 'remap_grid_T42.nc' >>> grid2_file = 'remap_grid_POP43.nc' >>> interp_file1 = 'rmp_T42_to_POP43_conserv.nc' >>> interp_file2 = 'rmp_POP43_to_T42_conserv.nc' - >>> map1_name = 'T42 to POP43 Conservative Mapping' + >>> map1_name = 'T42 to POP43 Conservative Mapping' >>> map2_name = 'POP43 to T42 Conservative Mapping' >>> map_method = 'conservative' >>> normalize_opt = 'frac' @@ -303,14 +303,14 @@ input to output grids. CDMS Regridder Constructor ~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 50, 90 :align: left "``regridFunction = Regridder(inputGrid, outputGrid)``", "Create a regridder function which interpolates a data array from input to output grid. - * `CDMS regridder functions`_ describes the calling sequence of this function. + * `CDMS regridder functions`_ describes the calling sequence of this function. * ``inputGrid`` and ``outputGrid`` are CDMS grid objects. **Note:** To set the mask associated with inputGrid or outputGrid, use the grid setMask function." @@ -323,7 +323,7 @@ function: SCRIP Regridder Constructor ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Constructor", "Description" :widths: 80, 90 :align: left @@ -337,7 +337,7 @@ SCRIP Regridder Constructor * ``'distwgt'``: distance-weighted interpolation. * It is only necessary to specify the map method if it is not defined in the file. * If ``checkGrid`` is 1 (default), the grid cells are checked for convexity, and 'repaired' if necessary. - * Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. + * Grid cells may appear to be nonconvex if they cross a ``0 / 2pi`` boundary. * The repair consists of shifting the cell vertices to the same side modulo 360 degrees." Regridder Functions @@ -358,7 +358,7 @@ A CDMS regridder function is an instance of the CDMS ``Regridder`` class. The function is associated with rectangular input and output grids. Typically its use is straightforward: * The function is passed an input array and returns the regridded array. - However, when the array has missing data, or the input and/or output + However, when the array has missing data, or the input and/or output grids are masked, the logic becomes more complicated. Step 1 @@ -407,7 +407,7 @@ grid cells which completely overlap input grid cells with missing values CDMS Regridder Function ~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Type", "Function", "Description" :widths: 40, 40, 80 :align: left @@ -425,13 +425,13 @@ CDMS Regridder Function * ``order`` is a string indicating the order of dimensions of the array. It has the form returned from ``variable.getOrder().`` * ``mask`` is a Numpy array, of datatype Integer or Float, consisting of a fractional number between 0 and 1. * A value of 1 or 1.0 indicates that the corresponding data value is to be ignored for purposes of regridding. - * A value of 0 or 0.0 indicates that the corresponding data value is valid. This is consistent with the convention for masks used by the MV2 module. + * A value of 0 or 0.0 indicates that the corresponding data value is valid. This is consistent with the convention for masks used by the MV2 module. * A fractional value between 0.0 and 1.0 indicates the fraction of the data value (e.g., the corresponding cell) to be ignored when regridding. This is useful if a variable is regridded first to grid A and then to another grid B; the mask when regridding from A to B would be (1.0 - f) where f is the maskArray returned from the initial grid operation using the ``returnTuple`` argument." DMS Regridder Function(cont'd) ~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Type", "Function", "Description" :widths: 40, 40, 80 :align: left @@ -442,10 +442,10 @@ DMS Regridder Function(cont'd) Variable, a TransientVariable of the same rank as the input array is returned, otherwise a masked array is returned. - * If ``mask`` is two-dimensional of the same shape as the input grid, it overrides the mask of the input grid. - * If the ``mask`` has more than two dimensions, it must have the same shape as ``array``. In this case, the ``missing`` data value is also ignored. Such an ndimensional mask is useful if the pattern of missing data varies with level (e.g., ocean data) or time. + * If ``mask`` is two-dimensional of the same shape as the input grid, it overrides the mask of the input grid. + * If the ``mask`` has more than two dimensions, it must have the same shape as ``array``. In this case, the ``missing`` data value is also ignored. Such an ndimensional mask is useful if the pattern of missing data varies with level (e.g., ocean data) or time. **Note:** If neither ``missing`` or ``mask`` is set, the default mask is obtained from the mask of the array if any." - "Array, Array", "``regridFunction (ar, missing=None, order=None, mask=None, returnTuple=1)``", "If called with the optional ``returnTuple`` + "Array, Array", "``regridFunction (ar, missing=None, order=None, mask=None, returnTuple=1)``", "If called with the optional ``returnTuple`` argument equal to 1, the function returns a tuple ``dataArray``, ``maskArray``). * ``dataArray`` is the result data array. * ``maskArray`` is a Float32 array of the same shape as ``dataArray``, such that ``maskArray[i,j]`` is fraction of the output grid cell [i,j] overlapping a non-missing cell of the grid." @@ -494,23 +494,23 @@ for source and target grids. SCRIP Regridder Functions ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Return Type", "Method", "Description" :widths: 30, 45, 80 :align: left - "Array or Transient-Variable", "[conservative, bilinear, and distance-weighted regridders] ``regridFunction(array)``", "Interpolate a gridded data array to a new grid. - The return value is the regridded data variable. + "Array or Transient-Variable", "[conservative, bilinear, and distance-weighted regridders] ``regridFunction(array)``", "Interpolate a gridded data array to a new grid. + The return value is the regridded data variable. * ``array`` is a Variable, MaskedArray, or Numpy array. - * The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. - * For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. + * The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. + * For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. * Similarly, if the input grid is generic with shape (2560,), the last dimension of the array must have that length." "Array or Transient-Variable", "[bicubic regridders] ``regridFunction(array, gradientLat, gradientLon, gradientLatLon)``", "Interpolate a gridded data array to a new grid, - using a bicubic regridder. + using a bicubic regridder. The return value is the regridded data variable. - * ``array`` is a Variable, MaskedArray, or Numpy array. - * The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. - * For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. + * ``array`` is a Variable, MaskedArray, or Numpy array. + * The rank of the array may be greater than the rank of the input grid, in which case the input grid shape must match a trailing portion of the array shape. + * For example, if the input grid is curvilinear with shape (64,128), the last two dimensions of the array must match. * Simiarly, if the input grid is generic with shape (2560,), the last dimension of the array must have that length. * ``gradientLat``: df/di (see the SCRIP documentation). Same shape as ``array``. * ``gradientLon``: df/dj. Same shape as ``array``. @@ -519,21 +519,21 @@ SCRIP Regridder Functions SCRIP Regridder Functions(con'td) ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. csv-table:: +.. csv-table:: :header: "Return Type", "Method", "Description" :widths: 30, 45, 80 :align: left - "Numpy array", "``getDestinationArea()`` [conservative regridders only]", "Return the area of the destination (output) grid cell. + "Numpy array", "``getDestinationArea()`` [conservative regridders only]", "Return the area of the destination (output) grid cell. * The array is 1-D, with length equal to the number of cells in the output grid." "Numpy array", "``getDestination Fraction()``", "Return the area fraction of the destination (output) - grid cell that participates in the regridding. + grid cell that participates in the regridding. * The array is 1-D, with length equal to the number of cells in the output grid." "CurveGrid or Generic-Grid", "``getInputGrid()``", "Return the input grid, or None if no input grid is associated with the regridder." "CurveGrid or Generic-Grid", "``getOutputGrid()``", "Return the output grid." "Numpy array", "``getSourceFraction()``", "Return the area fraction of the source (input) - grid cell that participates in the regridding. + grid cell that participates in the regridding. * The array is 1-D, with length equal to the number of cells in the input grid" Examples @@ -548,7 +548,7 @@ Regrid data to a uniform output grid. :: - + >>> import cdms2 >>> from regrid2 import Regridder >>> f = cdms2.open('clt.nc') @@ -645,7 +645,7 @@ Generate an array of zonal mean values. Regrid an array with missing data, and calculate the area-weighted mean of the result. -:: +:: >>> import cdms2 >>> from cdms2.MV2 import * diff --git a/docs/source/manual/cdms_5.rst b/docs/source/manual/cdms_5.rst index 39a6837b..5f227f1e 100644 --- a/docs/source/manual/cdms_5.rst +++ b/docs/source/manual/cdms_5.rst @@ -47,23 +47,23 @@ Plotting a Gridded Variable :: - >>> import cdms2, vcs - >>> f = cdms2.open("clt.nc") - >>> clt = f.variables['clt'] - >>> sample = clt[0,:] - >>> w=vcs.init() - >>> w.plot(sample) + >>> import cdms2, vcs + >>> f = cdms2.open("clt.nc") + >>> clt = f.variables['clt'] + >>> sample = clt[0,:] + >>> w=vcs.init() + >>> w.plot(sample) - >>> f.close() + >>> f.close() **Notes:** -.. csv-table:: +.. csv-table:: :header: "Line", "Notes" :widths: 10, 90 "3","Get a horizontal slice, for the first time point." - "4","Create a VCS Canvas ``w``." + "4","Create a VCS Canvas ``w``." "5", "Plot the data. Because sample is a transient variable, it encapsulates all the time, latitude, longitude, and attribute information." "7", "Close the file. This must be done after the reference to the persistent variable ``ps l``." @@ -79,14 +79,14 @@ Using A Plot Keywords :: - >>> import cdms2, vcs - >>> f = cdms2.open("clt.nc") - >>> clt = f.variables['clt'] - >>> sample = clt[0,:] - >>> w=vcs.init() - >>> w.plot(sample, units='percent', file_comment='', long_name="Total Cloud", comment1="Example plot", hms="00:00:00", ymd="1979/01/01") + >>> import cdms2, vcs + >>> f = cdms2.open("clt.nc") + >>> clt = f.variables['clt'] + >>> sample = clt[0,:] + >>> w=vcs.init() + >>> w.plot(sample, units='percent', file_comment='', long_name="Total Cloud", comment1="Example plot", hms="00:00:00", ymd="1979/01/01") - >>> f.close() + >>> f.close() **Note:** Keyword arguments can be listed in any order. @@ -99,16 +99,16 @@ this example selects and plots a time-latitude slice: :: - >>> import cdms2, vcs - >>> f = cdms2.open("clt.nc") - >>> clt = f.variables['clt'] - >>> samp = clt[:,:,0] - >>> w = vcs.init() - >>> w.plot(samp, name='Total Cloudiness') + >>> import cdms2, vcs + >>> f = cdms2.open("clt.nc") + >>> clt = f.variables['clt'] + >>> samp = clt[:,:,0] + >>> w = vcs.init() + >>> w.plot(samp, name='Total Cloudiness') -.. csv-table:: +.. csv-table:: :header: "Line", "Notes" :widths: 10, 90 @@ -123,7 +123,7 @@ variable. The result variable ``samp`` can be plotted directly: :: - >>> import cdms2, vcs + >>> import cdms2, vcs >>> f = cdms2.open("clt.nc") >>> clt = f.variables['clt'] >>> samp = clt(time = (0.0,100.0), longitude = 180.0, squeeze=1) @@ -150,11 +150,11 @@ where: two and five dimensions. The last dimensions of the array is termed the 'x' dimension, the next-to-last the 'y' dimension, then 'z', 't', and 'w'. - + - For example, if array is three-dimensional, the axes are (z,y,x), and if array is four-dimensional, the axes are (t,z,y,x). - - **Note:** that the t dimension need have no connection with time; any + + **Note:** that the t dimension need have no connection with time; any spatial axis can be mapped to any plot dimension.) - For a graphics method which is two-dimensional, such as boxfill, @@ -195,18 +195,18 @@ Plot Keywords "comment2", "string", "Comment plotted above ``comment1``" "comment3", "string", "Comment plotted above ``comment2``" "continents", "0 or 1", "if ``1``, plot continental outlines (default:plot if - * ``xaxis`` is longitude, + * ``xaxis`` is longitude, * ``yaxis`` is latitude -or- ``xname`` is 'longitude' and ``yname`` is 'latitude'" "file_comment", "string", "Comment, * Defaults to ``variable.parent.comment``" - "grid", "CDMS grid object", "Grid associated with the data. + "grid", "CDMS grid object", "Grid associated with the data. * Defaults to ``variable.getGrid()``" "hms", "string", "Hour, minute, second" - "long_name", "string", "Descriptive variable name, + "long_name", "string", "Descriptive variable name, * Defaults to ``variable.long_name``." - "missing_value", "same type as array", "Missing data value, + "missing_value", "same type as array", "Missing data value, * Defaults to ``variable.getMissing()``" - "``name``", "string", "Variable name, + "``name``", "string", "Variable name, * Defaults to ``variable.id``" "time", "cdtime relative or absolute", "Time associated with the data. Example: @@ -222,30 +222,30 @@ Plot Keywords(cont'd) "units", "string", "Data units. * Defaults to ``variable.units``" - "variable", "CDMS variable object", "Variable associated with the data. + "variable", "CDMS variable object", "Variable associated with the data. * The variable grid must have the same shape as the data array." "xarray (``[y|z|t|w]array``)", "1-D Numpy array", "*Rectangular grids only*. * Array of coordinate values, having the same length as the corresponding dimension. * Defaults to ``xaxis[:\] (y|z|t|waxis[:])``" - "xaxis (``[y|z|t|w]axis``)", "CDMS axis object", "*Rectangular grids only*. + "xaxis (``[y|z|t|w]axis``)", "CDMS axis object", "*Rectangular grids only*. Axis object. - * ``xaxis`` defaults to ``grid.getAxis(0)`` + * ``xaxis`` defaults to ``grid.getAxis(0)`` * ``yaxis`` defaults to ``grid.getAxis(1)``" - "xbounds (``ybounds``)", "2-D Numpy array", "*Rectangular grids only*. - * Boundary array of shape ``(n,2)`` where ``n`` is the axis length. + "xbounds (``ybounds``)", "2-D Numpy array", "*Rectangular grids only*. + * Boundary array of shape ``(n,2)`` where ``n`` is the axis length. * Defaults to ``xaxis.getBounds()``, or ``xaxis.genGenericBounds()`` if ``None``, similarly for ``ybounds``." - "xname (``[y|z|t|w]name``)", "string", "*Rectangular grids only*. - Axis name. + "xname (``[y|z|t|w]name``)", "string", "*Rectangular grids only*. + Axis name. * Defaults to ``xaxis.id`` (``[y|z|t|w]axis.id``)" "xrev (``yrev``)", "0 or 1", "If ``xrev`` (``yrev``) is 1, reverse the direction of the ``x-axis (y-axis)``. * Defaults to 0, with the following exceptions: * If the ``y-axis`` is latitude, and has decreasing values, ``yrev`` defaults to 1 * If the ``y-axis`` is a vertical level, and has increasing pressure levels, ``yrev`` defaults to 1." - "xunits (``[y|z|t|w]units``)", "string", "*Rectangular grids only*. Axis units. + "xunits (``[y|z|t|w]units``)", "string", "*Rectangular grids only*. Axis units. * Defaults to ``xaxis.units`` (``[y|z|t|w]axis.units``)." -b + diff --git a/docs/source/manual/cdms_6.rst b/docs/source/manual/cdms_6.rst index 273cc837..bf7eeb67 100644 --- a/docs/source/manual/cdms_6.rst +++ b/docs/source/manual/cdms_6.rst @@ -44,14 +44,14 @@ where - ``element-content`` depends on the type of element. It is either a list of elements, or text which defines the element values. For example, the content of an axis element either is a list of axis - values, or is a linear element. + values, or is a linear element. - For datasets, the content is the blank-separated list of elements corresponding to the axes, grids, and variables contained in the dataset. The CDML elements are: CDML Tags -^^^^^^^^^ -.. csv-table:: +^^^^^^^^^ +.. csv-table:: :header: "Tag", "Description" :widths: 30,80 @@ -135,7 +135,7 @@ element. ``CDML-document ::= prolog dataset-element`` The prolog defines the XML version, and the Document Type Definition -(DTD), a formal specification of the document syntax. +(DTD), a formal specification of the document syntax. See https://www.w3.org/TR/1998/REC-xml-19980210 for a formal definition of XML Version 1.0. @@ -157,7 +157,7 @@ defined. Dataset Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. csv-table:: +.. csv-table:: :header: "Attribute", "Req?", "CF", "GDT", "Notes" :widths: 18, 9, 7, 7, 80 @@ -175,7 +175,7 @@ Dataset Attributes "institution", "N", "Y", "Y", "Who made or supplied the data" "production", "N", "N", "Y", "How the data was produced (see source)" "project", "N", "N", "N", "Project associated with the data Example: 'CMIP 2'" - "references", "N", "Y", "N", "Published or web-based references that describe the data or methods used to produce it" + "references", "N", "Y", "N", "Published or web-based references that describe the data or methods used to produce it" "source", "N", "Y", "N", "The method of production of the original data." "template", "N", "N", "N", "Filename template. This is an alternate mechanism, other than cdms_filemap, for describing the file mapping. See ‘cdimport -h’ for details." "title", "N", "Y", "N", "A succinct description of the data." @@ -261,14 +261,14 @@ Axis Elements "modulo", "N", "N", "Y", "Arithmetic modulo of an axis with circular topology." "month_lengths", "N", "Y", "N", "Length of each month in a non-leap year for a user-defined calendar." "name_in_file", "N", "N", "N", "Name of the axis in the underlying file(s). See id." - "partition", "N", "N", "N", "How the axis is split across files." - "partition_length", "N", "N", "N", "Number of axis points for which data is actually defined. If data is missing for some values, this will be smaller than the length." + "partition", "N", "N", "N", "How the axis is split across files." + "partition_length", "N", "N", "N", "Number of axis points for which data is actually defined. If data is missing for some values, this will be smaller than the length." "positive", "N", "Y", "Y", "Direction of positive for a vertical axis" "standard_name", "N", "Y", "N", "Reference to an entry in the standard name table." "topology", "N", "N", "Y", "Axis topology. * 'circular' | 'linear'" "units", "Y", "Y", "Y", "Units of a physical quantity" - "weights", "N", "N", "N", "Name of the weights array" + "weights", "N", "N", "N", "Name of the weights array" Partition attribute ^^^^^^^^^^^^^^^^^^^ @@ -279,10 +279,10 @@ is split across files. It is a list of the start and end indices of each axis partition. FIGURE 4. Partitioned axis - + .. figure:: /images/timeLine.jpg - :alt: + :alt: For example, Figure 4 shows a time axis, representing the 36 months, January 1980 through December 1982, with December 1981 missing. The @@ -307,7 +307,7 @@ rectilinear in topology, 6.5 RectGrid Attributes ^^^^^^^^^^^^^^^^^^^^^^^ - + .. raw:: html @@ -324,7 +324,7 @@ rectilinear in topology, :: idYNGrid identifier - typeYN

Grid classification

"gaussian" | "uniform" + typeYN

Grid classification

"gaussian" | "uniform" | "equalarea" |"generic"

Default: "generic"

latitudeYNLatitude axis name longitudeYNLongitude axis name @@ -352,7 +352,7 @@ the length. ``variable-element ::=`` **** ``variable-content`` **** -``variable-content ::=`` variable-domain extra-attributeelement\*\` +``variable-content ::=`` variable-domain extra-attributeelement\*`` ``variable-domain ::=`` **** ``domain-element*`` **** @@ -380,7 +380,7 @@ Variable Attributes "``grid_name``", "N", "N", "N", "Id of the grid." "``grid_type``", "N", "N", "N", "gaussian, uniform, equalarea, generic" "``long_name``", "N", "Y", "Y", "Long description of a physical quantity." - "``missing_value``", "N", "Y", "Y", "Value used for data that are unknown or missing." + "``missing_value``", "N", "Y", "Y", "Value used for data that are unknown or missing." "``name_in_file``", "N", "N", "N", "Name of the variable in the underlying file(s). See id." "``scale_factor``", "N", "Y", "Y", "Multiplicative factor for packing data. See add_offset." "``standard_name``", "N", "Y", "N", "Reference to an entry in the standard name table." @@ -426,7 +426,6 @@ Dataset "sample" has two variables, and six axes. indicates that variable ``u`` is contained in file u\_2000.nc for time index 0, u\_2001.nc for time index 1, etc. -{% highlight xml %} .. raw:: html @@ -434,70 +433,69 @@ Dataset "sample" has two variables, and six axes. :: - + - [-90. -78. -66. -54. -42. -30. -18. -6. 6. 18. 30. 42. 54. 66. 78. 90.] + [-90. -78. -66. -54. -42. -30. -18. -6. 6. 18. 30. 42. 54. 66. 78. 90.] :: - >>> >> id ="longitude" - >>> length="32" - >>> units="degrees_east" - >>> datatype="Double" - >>> > - >>> - >>> [ 0. 11.25 22.5 33.75 45. 56.25 67.5 78.75 90. - >>> - >>> 101.25 112.5 123.75 135. 146.25 157.5 168.75 180. 191.25 - >>> - >>> 202.5 213.75 225. 236.25 247.5 258.75 270. 281.25 292.5 - >>> - >>> 303.75 315. 326.25 337.5 348.75] - >>> - >>> - >>> >> id ="time" - >>> partition="[0 1 1 2 2 3]" - >>> calendar="gregorian" - >>> units="days since 2000-1-1" - >>> datatype="Double" - >>> length="3" - >>> name_in_file="time" - >>> > - >>> - >>> [ 0. 366. 731.] - >>> - >>> - >>> >> id ="u" - >>> missing_value="-99.9" - >>> units="m/s" - >>> datatype="Double" - >>> > - >>> - >>> - >>> - >>> - >>> - >>> - >>> - >>> >> id ="v" - >>> missing_value="-99.9" - >>> units="m/s" - >>> datatype="Double" - >>> > - >>> - >>> - >>> - >>> - >>> - >>> - >>> - >>> {% endhighlight %} - - - - - + + + [ 0. 11.25 22.5 33.75 45. 56.25 67.5 78.75 90. + + 101.25 112.5 123.75 135. 146.25 157.5 168.75 180. 191.25 + + 202.5 213.75 225. 236.25 247.5 258.75 270. 281.25 292.5 + + 303.75 315. 326.25 337.5 348.75] + + + + + [ 0. 366. 731.] + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/source/manual/cdms_7.rst b/docs/source/manual/cdms_7.rst index 5ec392de..350cc679 100644 --- a/docs/source/manual/cdms_7.rst +++ b/docs/source/manual/cdms_7.rst @@ -23,12 +23,12 @@ CDMS assumes that there is some regularity in how datasets are partitioned: - A variable can be partitioned (split across files) in at most two - dimensions. + dimensions. - The partitioned dimension(s) must be either time or vertical level dimensions; variables may not be partitioned across - longitude or latitude. + longitude or latitude. - Datasets can be parti-tioned by variable as - well. + well. - For example, one set of files might contain heat fluxes, while another set contains wind speeds. @@ -52,7 +52,7 @@ The syntax of the ``cdscan`` command is or - - cdscan [options] -f file_list + - cdscan [options] -f file_list where @@ -64,41 +64,41 @@ Output is written to standard output by default. Use the -x option to specify an output filename. CDScan Command Options -^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: "Option", "Description" :widths: 20, 80 - "``-a alias_file``", "Change variable names to the aliases defined in an alias file. - Each line of the alias file consists of two blank separated fields: - * ``variable_id alias``. + "``-a alias_file``", "Change variable names to the aliases defined in an alias file. + Each line of the alias file consists of two blank separated fields: + * ``variable_id alias``. * ``variable_id`` is the ID of the variable in the file, and - * ``alias`` is the name that will be substituted for it in the output dataset. + * ``alias`` is the name that will be substituted for it in the output dataset. * Only variables with entries in the ``alias_file`` are renamed." - "``-c calendar``", "Specify the dataset calendar attribute. + "``-c calendar``", "Specify the dataset calendar attribute. One of: * gregorian (default) * julian * noleap * proleptic_gregorian - * standard + * standard * 360_day" - "``-d dataset_id``", "String identifier of the dataset. + "``-d dataset_id``", "String identifier of the dataset. * Should not contain blanks or non-printing characters. * Default: 'None'" - "``-e newattr``", "Add or modify attributes of a file, variable, or axis. + "``-e newattr``", "Add or modify attributes of a file, variable, or axis. The form of ``newattr`` is either: * ``var.attr = value`` to modify a variable or attribute, or * ``.attr = value`` to modify a global (file) attribute. * In either case, value may be quoted to preserve spaces or force the attribute to be treated as a string. * If value is not quoted and the first character is a digit, it is converted to integer or floating-point. This option does not modify the input datafiles. See notes and examples below." "``--exclude var,var,...``", "Exclude specified variables. - * The argument is a comma-separated list of variables containing no blanks. + * The argument is a comma-separated list of variables containing no blanks. * Also see ``--include``." CDScan Command Options(cont'd) -^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: "Option", "Description" @@ -108,49 +108,49 @@ CDScan Command Options(cont'd) "``-h``", "Print a help message." "``-i time_delta``", "Causes the time dimension to be represented as linear, producing a more compact representation. - - This is useful if the time dimension is very long. - * ``time_delta`` is a float or integer. + - This is useful if the time dimension is very long. + * ``time_delta`` is a float or integer. * For example, if the time delta is 6 hours, and the reference units are ``hours since xxxx`` , set the time delta to 6. See the ``-r`` option. See Note 2." "``--include var,var,...``", "Only include specified variables in the output. - * The argument is a comma-separated list of variables containing no blanks. + * The argument is a comma-separated list of variables containing no blanks. * Also see ``--exclude``." - "``-j``", "Scan time as a vector dimension. + "``-j``", "Scan time as a vector dimension. * Time values are listed individually. **Note:** Turns off the -i option." "``-l levels``", "Specify that the files are partitioned by vertical level. That is, data for different - vertical levels may appear in different files. - * ``levels`` is a comma-separated list of levels containing no blanks. + vertical levels may appear in different files. + * ``levels`` is a comma-separated list of levels containing no blanks. * See Note 3." "``-m levelid``", "Name of the vertical level dimension. - * The default is the vertical dimension as determined by CDMS. + * The default is the vertical dimension as determined by CDMS. * See Note 3." CDScan Command Options(cont'd) -^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: "Option", "Description" :widths: 20, 80 - "``-p template``", "Add a file template string, for compatibility with pre-V3.0 datasets. + "``-p template``", "Add a file template string, for compatibility with pre-V3.0 datasets. * ``cdimport -h`` describes template strings." "``-q``", "Quiet mode." "``-r time_units``", "Time units of the form ``units since yyyy-mm-dd hh:mi:ss``, where: * ``units`` is one of 'year', 'month', 'day', 'hour', 'minute', 'second'." - "``-s suffix_file``", "Append a suffix to variable names, depending on the directory containing the data file. - This can be used to distinguish variables having the same name but + "``-s suffix_file``", "Append a suffix to variable names, depending on the directory containing the data file. + This can be used to distinguish variables having the same name but generated by different models or ensemble runs. - * ``suffix_file`` is the name of a file describing a mapping between directories and suffixes. - * Each line consists of two blank-separated fields: ``directory suffix``. - * Each file path is compared to the directories in the suffix file. + * ``suffix_file`` is the name of a file describing a mapping between directories and suffixes. + * Each line consists of two blank-separated fields: ``directory suffix``. + * Each file path is compared to the directories in the suffix file. * If the file path is in that directory or a subdirectory, the corresponding suffix is appended to the variable IDs in the file. - * If more than one such directory is found, the first directory found is used. + * If more than one such directory is found, the first directory found is used. * If no match is made, the variable ids are not altered. Regular expressions can be used: see the example in the Notes section." - "``-t timeid``", "ID of the partitioned time dimension. + "``-t timeid``", "ID of the partitioned time dimension. * The default is the name of the time dimension as determined by CDMS. * See Note 1." - "``--time-linear tzero,delta,units[,calendar]``", "Override the time dimensions(s) with a linear time dimension. + "``--time-linear tzero,delta,units[,calendar]``", "Override the time dimensions(s) with a linear time dimension. The arguments are comma-separated list: * zero is the initial time point, a floating-point value. * delta is the time delta, floating-point. @@ -178,7 +178,7 @@ CDScan Command Options(cont'd) - Set the global file attribute 'newattr' to 'newvalue'. -- The ``[--time-linear]`` option overrides the time values in the file(s). The resulting dimension does +- The ``[--time-linear]`` option overrides the time values in the file(s). The resulting dimension does not have any gaps. In contrast, the ``[-i]``, ``[-r]`` options use the specified time units (from ``[-r]``), and calendar from ``[-c]`` if specified, to convert the file times to the new units. The resulting linear dimension may have gaps. @@ -189,8 +189,8 @@ CDScan Command Options(cont'd) Examples ^^^^^^^^ -- cdscan -c noleap -d test -x test.xml [uv]\*.nc -- cdscan -d pcmdi\_6h -i 0.25 -r 'days since 1979-1-1' *6h*.ctl +- cdscan -c noleap -d test -x test.xml [uv]\*.nc +- cdscan -d pcmdi\_6h -i 0.25 -r 'days since 1979-1-1' *6h*.ctl File Formats ^^^^^^^^^^^^ diff --git a/docs/source/manual/cdms_appendix.rst b/docs/source/manual/cdms_appendix.rst index 3fcc52a6..46883120 100644 --- a/docs/source/manual/cdms_appendix.rst +++ b/docs/source/manual/cdms_appendix.rst @@ -30,12 +30,12 @@ applications to treat the behavior of, say a dataset axis and file axis, as identical. .. figure:: /images/cdms_classes.jpg - :scale: 95% - :alt: + :scale: 95% + :alt: FIGURE 1. CDMS Classes - - + + @@ -68,7 +68,7 @@ Release 4.0 CDMS version 4.0 adds support for nonrectangular grids: -- The following grid classes were added: +- The following grid classes were added: * AbstractHorizontalGrid * AbstractCurve-Grid * AbstractGenericGrid @@ -195,9 +195,9 @@ AbstractRectGrid InternalAttributes '''''''''''''''''' -- The class InternalAttributes was added. +- The class InternalAttributes was added. - It has methods: - + * add\_internal\_attribute * is\_internal\_attribute * replace\_external\_attributes @@ -235,29 +235,29 @@ Table Slab Methods ^^^^^^^^^^^^^^^^^^^^^^ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 20,50,80 :align: left - "Various", "``getdimattribute(dim, field)``", "Get the value of a dimension attribute. - * ``dim`` is the dimension number, an integer in the range 0..rank- 1. + "Various", "``getdimattribute(dim, field)``", "Get the value of a dimension attribute. + * ``dim`` is the dimension number, an integer in the range 0..rank- 1. * ``field`` is a string, one of: 'name', 'values', 'length', 'units', 'weights', 'bounds'." "Various", "``getattribute(name)``", "Get the value of an attribute. - * ``name`` is the string name of the attribute. - The following special names can always be used: + * ``name`` is the string name of the attribute. + The following special names can always be used: * ``filename``, ``comments``, ``grid_name``, ``grid_type``, ``time_statistic``, ``long_name``, ``units``." - "None", "``info(flag=None, device=sys.stdout)``", "Print slab information. + "None", "``info(flag=None, device=sys.stdout)``", "Print slab information. * If ``flag`` is nonzero, dimension values, weights, and bounds are also printed. Output is sent to ``device``." - "List", "``listall(all=None)``", "Print slab information. + "List", "``listall(all=None)``", "Print slab information. * If ``all`` is nonzero, dimension values, weights, and bounds are also printed." "List", "``listdimattributes(dim, field)``", "List dimension attributes. Returns a list of string attribute names which can be input to - ``getdimattribute``. - * ``dim`` is the dimension number, an integer in the range 0..rank-1. + ``getdimattribute``. + * ``dim`` is the dimension number, an integer in the range 0..rank-1. * ``field`` is a string, one of: 'name', 'values', 'length', 'units', 'weights', 'bounds'." - "None", "``setattribute(name, value)``", "Set an attribute. - * ``name`` is the string name of the attribute. + "None", "``setattribute(name, value)``", "Set an attribute. + * ``name`` is the string name of the attribute. * ``value`` is the value of the attribute." @@ -269,7 +269,7 @@ cuDataset Table cuDataset Methods ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 20, 50, 80 :align: left @@ -278,26 +278,26 @@ Table cuDataset Methods "None", "``default_variable(vname``)", "Set the default variable name. * ``vname`` is the string variable name." "Array", "``dimensionarray(dname, vname=None``)", "Values of the axis named dname. - * ``dname1`` is the string axis name. - * ``vname`` is the string variable name. + * ``dname1`` is the string axis name. + * ``vname`` is the string variable name. **Note**: The default is the variable name set by default_variable." - "Axis", "``dimensionobject(dname, vname=None)``", "Get an axis. dname is the string name of an axis. - * ``vname`` is a string variable name. + "Axis", "``dimensionobject(dname, vname=None)``", "Get an axis. dname is the string name of an axis. + * ``vname`` is a string variable name. **Note:** The default is the variable name set by default_variable." - "Various", "``getattribute (vname, attribute``)", "Get an attribute value. - * ``vname`` is a string variable name. + "Various", "``getattribute (vname, attribute``)", "Get an attribute value. + * ``vname`` is a string variable name. * ``attribute`` is the string attribute name." "String", "``getdimensionunits (dname,vname=None``)", "Get the units for the given dimension. * ``dname`` is the string name of an axis. - * ``vname`` is a string variable name. + * ``vname`` is a string variable name. **Note:** The default is the variable name set by default_variable." - "Various", "``getglobal (attribute)``", "Get the value of the global attribute. + "Various", "``getglobal (attribute)``", "Get the value of the global attribute. * ``attribute`` is the string attribute name." Table cuDataset Methods(cont'd) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 20, 50, 80 :align: left @@ -305,7 +305,7 @@ Table cuDataset Methods(cont'd) "Variable", "``getslab (vname, \*args)``", "Read data for a variable. * ``vname`` is the string name of the variable. - * ``args`` is an argument list corresponding to the dimensions of the variable. + * ``args`` is an argument list corresponding to the dimensions of the variable. Arguments for each dimension can be: * ':' or None -- select the entire dimension * Ellipsis -- select entire dimensions between the ones given. @@ -315,11 +315,11 @@ Table cuDataset Methods(cont'd) * ``vname`` is the string name of the variable. **Note:** If all is non-zero, dimension values, weights, and bounds are returned as well" "List", "``listattribute (vname=None )``", "Return a list of attribute names. - * ``vname`` is the name of the variable. + * ``vname`` is the name of the variable. **Note:** The default is the variable name set by default_variable." "List", "``listdimension (vname=None)``", "Return a list of the dimension names associated with - a variable. - * ``vname`` is the name of the variable. + a variable. + * ``vname`` is the name of the variable. **Note:** The default is the variable name set by default_variable." "List", "``listglobal ()``", "Return a list of the global attribute names." "List", "``listvariable ()``", "Return a list of the variables in the file." @@ -327,20 +327,20 @@ Table cuDataset Methods(cont'd) Table cuDataset Methods(cont'd) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. csv-table:: +.. csv-table:: :header: "Type", "Method", "Definition" :widths: 20, 50, 80 :align: left - "None", "``showall (vname=None, all=None, device=sys.stdout)``", "Print a description of the variable. + "None", "``showall (vname=None, all=None, device=sys.stdout)``", "Print a description of the variable. * ``vname`` is the string name of the variable. **Note:** If all is non-zero, dimension values, weights, and bounds are returned as well. Output is sent to device." "None", "``showattribute (vname=None, device=sys.stdout)``", "Print the attributes of a variable. * ``vname`` is the string name of the variable. **Note:** Output is sent to device." - "None", "``showdimension (vname=None, device=sys.stdout)``", "Print the dimension names associated with a variable. - * ``vname`` is the string name of the variable. - **Note:** Output is sent to device." + "None", "``showdimension (vname=None, device=sys.stdout)``", "Print the dimension names associated with a variable. + * ``vname`` is the string name of the variable. + **Note:** Output is sent to device." "None", "``showglobal (device=sys.stdout)``", "Print the global file attributes. Output is sent to device." "None", "``showvariable (device=sys.stdout)``", "Print the list of variables in the file." diff --git a/docs/source/manual/sample_data.rst b/docs/source/manual/sample_data.rst index c6685723..e1ae3d07 100644 --- a/docs/source/manual/sample_data.rst +++ b/docs/source/manual/sample_data.rst @@ -1,6 +1,14 @@ CDMS Sample Dataset ------------------- +THREDDS Data Server (TDS) +''''''''''''''''''''''''' + +* https://aims3.llnl.gov/thredds/catalog/esgcet/254/CDAT-sample.v1.html + +Direct https donwload +''''''''''''''''''''' + * https://cdat.llnl.gov/cdat/sample_data/161122_RobertPincus_multiple_input4MIPs_radiation_RFMIP_UColorado-RFMIP-20161122_none.nc * https://cdat.llnl.gov/cdat/sample_data/20160520.A_WCYCL1850.ne30_oEC.edison.alpha6_01_ANN_climo_Q.nc * https://cdat.llnl.gov/cdat/sample_data/area_weights.nc