chapter2.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#  CDMS Python Application Programming Interface"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## A First Example\n",
    "\n",
    "\n",
    "The following Python script reads January and July monthly temperature\n",
    "data from an input dataset, averages over time, and writes the results\n",
    "to an output file. The input temperature data is ordered (time,\n",
    "latitude, longitude)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Makes the CDM2S and MV2 modules available.\n",
    "\n",
    "* MV2 defines arithmetic functions.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cdms2, cdat_info\n",
    "from cdms2 import MV2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Opens a netCDF file read-only. \n",
    "* The result jones is a dataset object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "jones = cdms2.open('https://aims3.llnl.gov/thredds/dodsC/user_pub_work/CDAT-sample/v1/tas_mo.nc')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Gets the surface air temperature variable. ‘tas’ is the name of the variable in the input dataset. \n",
    "* This does not actually read the data.\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "tasvar = jones['tas']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Read all January monthly mean data into a variable jans.\n",
    "* Variables can be sliced like arrays.\n",
    "* The slice operator [0::12] means take every 12th slice from dimension 0, starting at index 0 and ending at the last index. \n",
    "* If the stride 12 were omitted, it would default to 1. \n",
    "\n",
    "**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, : , :]. \n",
    "\n",
    "\n",
    "**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.\"\n",
    "       "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "jans = tasvar[0::12]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Reads all July data into a masked array julys."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "julys = tasvar[6::12]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calculate the average January value for each grid zone.\n",
    "* Any missing data is handled automatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "janavg = MV2.average(jans)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set the variable id and long\\_name attributes. \n",
    "* The id is used as the name of the variable when plotted or written to a file.\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "janavg.id = \"tas_jan\"\n",
    "janavg.long_name = \"mean January surface temperature\"\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Calculate the average July value for each grid zone."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "julyavg = MV2.average(julys)\n",
    "julyavg.id = \"tas_jul\"\n",
    "julyavg.long_name = \"mean July surface temperature\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Create a new netCDF output file named \"***janjuly.nc***\" to hold the results.\n",
    "\n",
    "Write the January average values to the output file. \n",
    "* The variable will have id “tas\\_jan” in the file.\n",
    "* \"**write**\" is a utility function which creates the variable in the file, then writes data to the variable.\n",
    "* A more general method of data output is first to create a variable, then set a slice of the variable.\n",
    "\n",
    "**Note:** that janavg and julavg have the same latitude and longitude information as tasvar. It is carried along with the computations.\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/software/anaconda53/envs/cdms2/lib/python3.6/site-packages/cdms2/dataset.py:2187: Warning: Files are written with compression and no shuffling\n",
      "You can query different values of compression using the functions:\n",
      "cdms2.getNetcdfShuffleFlag() returning 1 if shuffling is enabled, 0 otherwise\n",
      "cdms2.getNetcdfDeflateFlag() returning 1 if deflate is used, 0 otherwise\n",
      "cdms2.getNetcdfDeflateLevelFlag() returning the level of compression for the deflate method\n",
      "\n",
      "If you want to turn that off or set different values of compression use the functions:\n",
      "value = 0\n",
      "cdms2.setNetcdfShuffleFlag(value) ## where value is either 0 or 1\n",
      "cdms2.setNetcdfDeflateFlag(value) ## where value is either 0 or 1\n",
      "cdms2.setNetcdfDeflateLevelFlag(value) ## where value is a integer between 0 and 9 included\n",
      "\n",
      "To produce NetCDF3 Classic files use:\n",
      "cdms2.useNetCDF3()\n",
      "To Force NetCDF4 output with classic format and no compressing use:\n",
      "cdms2.setNetcdf4Flag(1)\n",
      "NetCDF4 file with no shuffling or deflate and noclassic will be open for parallel i/o\n",
      "  \"for parallel i/o\", Warning)\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<cdms2.fvariable.FileVariable at 0x7f719809f630>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "out = cdms2.open('janjuly.nc','w')\n",
    "out.write(janavg)\n",
    "out.write(julyavg)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set the global attribute \"**comment**\".\n",
    "* Close the output file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "out.comment = \"Average January/July from Jones dataset\"\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "jones.close()\n",
    "out.close()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Look at the resulting file using ncdump.  The written file follows the CF-1 connvention."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "netcdf janjuly {\n",
      "variables:\n",
      "\tfloat tas_jan ;\n",
      "\t\ttas_jan:subgrid = \"time:mean\" ;\n",
      "\t\ttas_jan:long_name = \"mean January surface temperature\" ;\n",
      "\t\ttas_jan:units = \"K\" ;\n",
      "\t\ttas_jan:axis = \"TZYX\" ;\n",
      "\t\ttas_jan:missing_value = 1.e+20f ;\n",
      "\t\ttas_jan:_FillValue = 1.e+20f ;\n",
      "\tfloat tas_jul ;\n",
      "\t\ttas_jul:subgrid = \"time:mean\" ;\n",
      "\t\ttas_jul:long_name = \"mean July surface temperature\" ;\n",
      "\t\ttas_jul:units = \"K\" ;\n",
      "\t\ttas_jul:axis = \"TZYX\" ;\n",
      "\t\ttas_jul:missing_value = 1.e+20f ;\n",
      "\t\ttas_jul:_FillValue = 1.e+20f ;\n",
      "\n",
      "// global attributes:\n",
      "\t\t:Conventions = \"CF-1.0\" ;\n",
      "\t\t:comment = \"Average January/July from Jones dataset\" ;\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "!ncdump -h janjuly.nc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "---\n",
    "\n",
    "## Cdms2 Module\n",
    "\n",
    "\n",
    "The cdms2 module is the Python interface to CDMS. The objects and methods in this chapter are made accessible with the command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cdms2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The functions described in this section are not associated with a class.\n",
    "Rather, they are called as module functions, e.g.,"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "file = cdms2.open('https://aims3.llnl.gov/thredds/dodsC/user_pub_work/CDAT-sample/v1/clt.nc')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**See Also**: [Cdms Module Functions](https://cdms.readthedocs.io/en/latest/manual/cdms_2.html#cdms-module-functions)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CdmsObj\n",
    "\n",
    "Get a list of all external attributes of obj."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['Conventions', 'comments', 'model', 'center', 'DODS_EXTRA.Unlimited_Dimension'])\n"
     ]
    }
   ],
   "source": [
    "extatts = file.attributes.keys()\n",
    "print(extatts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CoordinateAxis\n",
    "\n",
    "A CoordinateAxis is a variable that represents coordinate information.\n",
    "It may be contained in a file or dataset, or may be transient\n",
    "(memoryresident). Setting a slice of a file CoordinateAxis writes to the file, and referencing a file CoordinateAxis slice reads data from the file. Axis objects are also used to define the domain of a Variable.\n",
    "\n",
    "CDMS defines several different types of CoordinateAxis objects. See [MV module](https://cdms.readthedocs.io/en/latest/manual/cdms_2.html#id4) documents methods that are common to all CoordinateAxis types. See [HorizontalGrid]( https://cdms.readthedocs.io/en/latest/manual/cdms_2.html#id6) specifies methods that are unique to 1D Axis objects."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "   id: longitude\n",
      "   Designated a longitude axis.\n",
      "   units:  degrees_east\n",
      "   Length: 72\n",
      "   First:  -180.0\n",
      "   Last:   175.0\n",
      "   Other axis attributes:\n",
      "      long_name: Longitude\n",
      "   Python id:  0x7f7196f07240\n",
      "\n"
     ]
    }
   ],
   "source": [
    "clt=file['clt']\n",
    "axis=clt.getAxis(2)\n",
    "print(axis)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### isCircular()\n",
    "\n",
    "Returns True if the axis has circular topology.\n",
    "\n",
    "An axis is defined as circular if:\n",
    "* axis.topology == 'circular', or\n",
    "* axis.topology is undefined, and the axis is a longitude.\n",
    "\n",
    "The default cycle for circular axes is 360.0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1\n"
     ]
    }
   ],
   "source": [
    "print(axis.isCircular())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### mapIntervalExt(interval)\n",
    "\n",
    "Map a coordinate interval to an index\n",
    "interval. interval is a tuple having one of the forms:\n",
    "* (x,y)\n",
    "* (x,y,indicator)\n",
    "* (x,y,indicator,cycle)\n",
    "\n",
    "None or ':'\n",
    "\n",
    "* where x and y are coordinates indicating the interval [x,y], and:\n",
    "  * 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 should be intersected with the axis\n",
    "  * 'n' - select node values which are contained in the interval\n",
    "  * 'b' -select axis elements for which the corresponding cell boundary intersects the interval\n",
    "  * 'e' - same as n, but include an extra node on either side\n",
    "  * 's' - select axis elements for which the cell boundary is a subset of the interval\n",
    "  \n",
    "The default indicator is ‘ccn’, that is, the interval is closed, and nodes in the interval are selected.\n",
    "\n",
    "If cycle is specified, the axis is treated as circular with the given cycle value.\n",
    "\n",
    "By default, if axis.isCircular() is true, the axis is treated as circular with a default modulus of 360.0.\n",
    "\n",
    "An interval of None or ':' returns the full index interval of the axis.\n",
    "\n",
    "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 intersection is empty.\n",
    "\n",
    "For an axis which is circular (axis.topology == 'circular'), (i,j) is interpreted as follows, where n = len(axis)\n",
    "\n",
    "if **0 <= i < n and 0 <= j <= n**, the interval does not wrap around the axis endpoint.\n",
    "\n",
    "otherwise the interval wraps around the axis endpoint.\n",
    "\n",
    "**see also**: mapinterval, variable.subregion()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(35, 37, 1)\n"
     ]
    }
   ],
   "source": [
    "print(axis.mapIntervalExt((-5.0,5.0,'co')))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### CdmsFile\n",
    "\n",
    "A ``CdmsFile`` is a physical file, accessible via the ``cdunif``\n",
    "interface. netCDF files are accessible in read-write mode. All other\n",
    "formats (DRS, HDF, GrADS/GRIB, POP, QL) are accessible read-only.\n",
    "\n",
    "As of CDMS V3, the legacy cuDataset interface is also supported by\n",
    "Cdms-Files. See “cu Module”."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The following reads data for variable ‘clt’, year 1980."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cdms2\n",
    "f = cdms2.open('https://aims3.llnl.gov/thredds/dodsC/user_pub_work/CDAT-sample/v1/clt.nc')\n",
    "x = f('clt', time=('1980-1','1981-1'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The following gets the axis named time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "axis name: time\n",
      "axis name: time\n"
     ]
    }
   ],
   "source": [
    "t = f.axes['time']\n",
    "print(\"axis name:\", t.id)\n",
    "t = f['time']\n",
    "print(\"axis name:\", t.id)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.9. MV2 Module\n",
    "\n",
    "The fundamental CDMS data object is the variable. A variable is comprised of:\n",
    "\n",
    "    a masked data array, as defined in the NumPy \"ma\" module.\n",
    "    a domain is an ordered list of axes and/or grids.\n",
    "    an attribute dictionary.\n",
    "\n",
    "MV2 can be imported with the command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "import MV2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For completeness MV2 provides access to all the \"numpy.ma\" functions. The functions not listed in the following tables are identical to the corresponding numpy.ma function: **allclose, allequal, common_fill_value, compress, create_mask, dot, e, fill_value, filled, get_print_limit, getmask, getmaskarray, identity, indices, innerproduct, isMV2, isMaskedArray, is_mask, isarray, make_mask, make_mask_none, mask_or, masked, pi, put, putmask, rank, ravel, set_fill_value, set_print_limit, shape, size**. See the documentation at https://github.com/numpy/numpy for a description of these functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(11, 17, 73, 144)\n",
      "(11, 3, 37, 144)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/software/anaconda53/envs/cdms2/lib/python3.6/site-packages/cdms2/fvariable.py:99: FutureWarning: Using a non-tuple sequence for multidimensional indexing is deprecated; use `arr[tuple(seq)]` instead of `arr[seq]`. In the future this will be interpreted as an array index, `arr[np.array(seq)]`, which will result either in an error or a different result.\n",
      "  result = result[revlist]\n"
     ]
    }
   ],
   "source": [
    "import cdms2\n",
    "fh = cdms2.open(\"https://aims3.llnl.gov/thredds/dodsC/user_pub_work/CDAT-sample/v1/ta_ncep_87-6-88-4.nc\")\n",
    "ta=fh['ta']\n",
    "print(ta.shape)\n",
    "data = ta.subRegion(':', (-45.0,45.0,'co'), (0.0, 180.0))\n",
    "print(data.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or equivalently:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(11, 17, 36, 73)\n"
     ]
    }
   ],
   "source": [
    "data = ta.subRegion(latitude=(-45.0,45.0,'co'), longitude=(0.0,180.0))\n",
    "print(data.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Read all data for ``March, 1980``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(1, 17, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "data = ta.subRegion(time=('1988-3','1988-4','co'))\n",
    "print(data.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selectors\n",
    "\n",
    "A selector is a specification of a region of data to be selected from a variable. For example, the statement:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(1, 12, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "x = ta(time='1988-1-1', level=(1000.0,100.0))\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "means `select the values of variable v for time ‘1979-1-1’ and levels 1000.0 to 100.0 inclusive, setting x to the result.` Selectors are generally used to represent regions of space and time.\n",
    "\n",
    "The form for using a selector is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(1, 12, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "from cdms2.selectors import Selector\n",
    "s =  Selector(time='1988-1-1', level=(1000.0,100.0))\n",
    "result = ta(s)\n",
    "print(result.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "where v is a variable and s is the selector. An equivalent form is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(1, 12, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "result = fh('ta', s)\n",
    "print(result.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "where f is a file or dataset, and ‘varid’ is the string ID of a variable.\n",
    "\n",
    "A selector consists of a list of selector components. \n",
    "\n",
    "For example, the selector:\n",
    "\n",
    "* **time='1979-1-1', level=(1000.0,100.0)**\n",
    " \n",
    "has two components: time=’1979-1-1’, and level=(1000.0,100.0). This illustrates that selector components can be defined with keywords, using the form:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=note>\n",
    "    <b>NOTE</b>\n",
    "    \n",
    "For the keywords time, level, latitude, and longitude, the selector can be used with any variable. If the corresponding axis is not found, the selector component is ignored. This is very useful for writing general purpose scripts. The required keyword overrides this behavior. These keywords take values that are coordinate ranges or index ranges as defined in See Index and Coordinate Intervals.</div>\n",
    "\n",
    "Another form of selector components is the positional form, where the component order corresponds to the axis order of a variable. For example:\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "x9 = ta(('1988-1-1','1988-2-1'),1000.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "reads data for the range (‘1988-1-1’,’1988-2-1’) of the first axis, and coordinate value ``1000.0`` of the second axis. Non-keyword arguments of the form(s) listed in Index and Coordinate Intervals are treated as positional. Such selectors are more concise, but not as general or flexible as the other types described in this section.\n",
    "\n",
    "Selectors are objects in their own right. This means that a selector can be defined and reused, independent of a particular variable. Selectors are constructed using the cdms.selectors.Selector class. The constructor takes an argument list of selector components. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cdms2.selectors import Selector\n",
    "sel = Selector(time=('1988-1-1','1988-2-1'), level=1000.)\n",
    "x1 = ta(sel)\n",
    "x2 = ta(sel)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For convenience CDMS provides several predefined selectors, which can be used directly or can be combined into more complex selectors. \n",
    "\n",
    "The selectors **time**, **level**, **latitude**, **longitude**, and **required** are equivalent to their keyword counterparts. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "from cdms2 import time, level\n",
    "x = ta(time('1988-1-1','1988-2-1'), level(1000.))\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and\n",
    "\n",
    "are equivalent. Additionally, the predefined selectors **latitudeslice**, **longitudeslice**, **levelslice**, and **timeslice** take arguments ``(startindex, stopindex[, stride])``:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "from cdms2 import timeslice, levelslice\n",
    "x = ta(timeslice(0,2), levelslice(16,17))\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Finally, a collection of selectors is defined in module cdutil.region:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "from cdutil.region import *\n",
    "\n",
    "NH=NorthernHemisphere=domain(latitude=(0., 90.))\n",
    "SH=SouthernHemisphere=domain(latitude=(-90., 0.))\n",
    "Tropics=domain(latitude=(-23.4,23.4))\n",
    "SPZ=AAZ=AntarcticZone=domain(latitude=(-90., -66.6))\n",
    "                             "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Selectors can be combined using the `&` operator, \n",
    "\n",
    "or by refining them in the call:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n",
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "from cdms2.selectors import Selector\n",
    "from cdms2 import level\n",
    "sel2 = Selector(time=('1988-1-1','1988-2-1'))\n",
    "sel3 = sel2 & level(1000.0)\n",
    "x1 = ta(sel3)\n",
    "print(x1.shape)\n",
    "x2 = ta(sel2, level=1000.0)\n",
    "print(x2.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Selector Examples\n",
    "\n",
    "CDMS provides a variety of ways to select or slice data. In the following examples, variable hus is contained in file ``sample.nc``, and is a function of **(time, level, latitude, longitude)**. Time values are monthly starting at 1987-6-1. There are 17 levels, the last level being 1000.0. The name of the vertical level axis is ‘level’. All the examples select the first two times and the last level. The last two examples remove the singleton level dimension from the result array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cdms2\n",
    "f = cdms2.open('https://aims3.llnl.gov/thredds/dodsC/user_pub_work/CDAT-sample/v1/ta_ncep_87-6-88-4.nc')\n",
    "ta = f.variables['ta']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Keyword selection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(3, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "x = ta(time=('19988-1-1','1988-2-1'), level=1000.)\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Interval indicator (see mapIntervalExt)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "x = ta(time=('1988-1-1','1988-3-1','co'), level=1000.)\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Axis ID (plev) as a keyword"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "\n",
    "x = ta(time=('1988-1-1','1988-2-1'), plev=1000.)\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Positional"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "\n",
    "x = ta(('1988-1-1','1988-2-1'),1000.0)\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Predefined selectors"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n",
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "\n",
    "from cdms2 import time, level\n",
    "x = ta(time('1988-1-1','1988-2-1'), level(1000.))\n",
    "print(x.shape)\n",
    "\n",
    "from cdms2 import timeslice, levelslice\n",
    "x = ta(timeslice(0,2), levelslice(16,17))\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Call file as a function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "\n",
    "x = f('ta', time=('1988-1-1','1988-2-1'), level=1000.)\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Python slices"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "x = ta(time=slice(0,2), level=slice(16,17))\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Selector objects"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 1, 73, 144)\n",
      "(2, 1, 73, 144)\n",
      "(2, 1, 73, 144)\n"
     ]
    }
   ],
   "source": [
    "\n",
    "from cdms2.selectors import Selector\n",
    "sel = Selector(time=('1988-1-1','1988-2-1'), level=1000.)\n",
    "x = ta(sel)\n",
    "print(x.shape)\n",
    "sel2 = Selector(time=('1988-1-1','1988-2-1'))\n",
    "sel3 = sel2 & level(1000.0)\n",
    "x = ta(sel3)\n",
    "print(x.shape)\n",
    "x = ta(sel2, level=1000.0)\n",
    "print(x.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "##### Squeeze singleton dimension (level)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(2, 73, 144)\n",
      "(2, 73, 144)\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/software/anaconda53/envs/cdms2/lib/python3.6/site-packages/numpy/ma/core.py:3174: FutureWarning: Using a non-tuple sequence for multidimensional indexing is deprecated; use `arr[tuple(seq)]` instead of `arr[seq]`. In the future this will be interpreted as an array index, `arr[np.array(seq)]`, which will result either in an error or a different result.\n",
      "  dout = self.data[indx]\n"
     ]
    }
   ],
   "source": [
    "x = ta[0:2,16]\n",
    "print(x.shape)\n",
    "\n",
    "x = ta(time=('1988-1-1','1988-2-1'), level=1000., squeeze=1)\n",
    "print(x.shape)\n",
    "\n",
    "f.close()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<style>\n",
       "div.note {    \n",
       "    background-color: #e5ffcc;\n",
       "    border-color: #dFb5b4;\n",
       "    border-left: 5px solid #dfb5b4;\n",
       "    padding: 0.5em;\n",
       "    }\n",
       " </style>\n",
       "div.warn {    \n",
       "    background-color: #fcf2f2;\n",
       "    border-color: #dFb5b4;\n",
       "    border-left: 5px solid #dfb5b4;\n",
       "    padding: 0.5em;\n",
       "    }\n",
       " </style>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 44,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.display import HTML\n",
    "def css_styling():\n",
    "    styles = open(\"./styles/custom.css\", \"r\").read()\n",
    "    return HTML(styles)\n",
    "css_styling()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}