From baac8051480260cee6069b70b034d619574ded25 Mon Sep 17 00:00:00 2001 From: Michael James Date: Wed, 3 Oct 2018 12:27:46 -0600 Subject: [PATCH] doc and readme updates, new datatyes document --- README.rst | 12 +++- docs/source/conf.py | 3 +- docs/source/datatypes.rst | 122 ++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 88 ++++++++++++++++----------- docs/source/install.rst | 37 ------------ 5 files changed, 186 insertions(+), 76 deletions(-) create mode 100644 docs/source/datatypes.rst delete mode 100644 docs/source/install.rst diff --git a/README.rst b/README.rst index e63ca66..0891668 100644 --- a/README.rst +++ b/README.rst @@ -46,6 +46,11 @@ AWIPS Python Data Access Framework :target: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github :alt: PRs Welcome +About +----- + +The python-awips package provides a data access framework for requesting grid and geometry datasets from an AWIPS `EDEX `_ server. AWIPS and python-awips packages are released and maintained by UCAR's `Unidata Program Center `_ in Boulder, Colorado. + Install ------- @@ -64,8 +69,11 @@ Conda Environment Requirements ------------ -- Python >= 2.7 -- pip install numpy shapely six +- python >= 2.7 +- numpy +- six +- shapely + Documentation ------------- diff --git a/docs/source/conf.py b/docs/source/conf.py index ad50249..a02eb5d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -38,6 +38,7 @@ extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode', + 'sphinx.ext.autosectionlabel', 'notebook_gen_sphinxext' ] @@ -57,7 +58,7 @@ master_doc = 'index' # General information about the project. project = 'python-awips' -copyright = '2016, Unidata' +copyright = '2018, Unidata' author = 'Unidata' # The version info for the project you're documenting, acts as replacement for diff --git a/docs/source/datatypes.rst b/docs/source/datatypes.rst new file mode 100644 index 0000000..7664a1e --- /dev/null +++ b/docs/source/datatypes.rst @@ -0,0 +1,122 @@ +==================== +Available Data Types +==================== + +.. _awips.dataaccess.DataAccessLayer.getGeometryData(request, times=[]): api/DataAccessLayer.html#awips.dataaccess.DataAccessLayer.getGeometryData + +.. _awips.dataaccess.DataAccessLayer.getGridData(request, times=[]): api/DataAccessLayer.html#awips.dataaccess.DataAccessLayer.getGridData + +.. _RadarCommon.get_hdf5_data(idra): api/RadarCommon.html + + + +binlightning +------------ + +- Shapely Point:: + + POINT (-65.65293884277344 -16.94915580749512) + +- returned by `awips.dataaccess.DataAccessLayer.getGeometryData(request, times=[])`_ +- example (GLM):: + + request = DataAccessLayer.newDataRequest() + request.setDatatype("binlightning") + request.addIdentifier("source", "GLMgr") + request.setParameters("intensity") + times = DataAccessLayer.getAvailableTimes(request) + response = DataAccessLayer.getGeometryData(request, times[-10:-1]) + for ob in response: + dir(ob.getGeometry()) + + +------------------ + + +grid +---- + +- NumPy Array +- returned by: `awips.dataaccess.DataAccessLayer.getGridData(request, times=[])`_ +- example:: + + request = DataAccessLayer.newDataRequest() + request.setDatatype("grid") + request.setLocationNames("RAP13") + request.setParameters("T") + request.setLevels("2.0FHAG") + cycles = DataAccessLayer.getAvailableTimes(request, True) + times = DataAccessLayer.getAvailableTimes(request) + fcstRun = DataAccessLayer.getForecastRun(cycles[-1], times) + response = DataAccessLayer.getGridData(request, [fcstRun[-1]]) + for grid in response: + data = grid.getRawData() + lons, lats = grid.getLatLonCoords() + + +------------------ + +warning +------- + +- Shapely MultiPolygon, Polygon:: + + MULTIPOLYGON ((-92.092348410 46.782322971, ..., -92.092348410 46.782322971), + (-90.948581075 46.992865960, ..., -90.948581075 46.992865960), + ... + (-92.274543999 46.652773000, ..., -92.280511999 46.656933000), + (-92.285491999 46.660741000, ..., -92.285491999 46.660741000)) + +- returned by `awips.dataaccess.DataAccessLayer.getGeometryData(request, times=[])`_ +- example:: + + request = DataAccessLayer.newDataRequest() + request.setDatatype("warning") + request.setParameters('phensig') + times = DataAccessLayer.getAvailableTimes(request) + response = DataAccessLayer.getGeometryData(request, times[-50:-1]) + for ob in response: + poly = ob.getGeometry() + site = ob.getLocationName() + pd = ob.getDataTime().getValidPeriod() + ref = ob.getDataTime().getRefTime() + + +------------------ + +radar +----- + +- NumPy Array +- returned by: `RadarCommon.get_hdf5_data(idra)`_ +- example:: + + request = DataAccessLayer.newDataRequest() + request.setDatatype("radar") + request.setLocationNames("klzk") + # Get latest time for site + datatimes = DataAccessLayer.getAvailableTimes(request) + dateTimeStr = str(datatimes[-1]) + #dateTimeStr = "2017-02-02 03:53:03" + buffer = 60 # seconds + dateTime = datetime.strptime(dateTimeStr, '%Y-%m-%d %H:%M:%S') + # Build timerange +/- buffer + beginRange = dateTime - timedelta(0, buffer) + endRange = dateTime + timedelta(0, buffer) + timerange = TimeRange(beginRange, endRange) + client = ThriftClient.ThriftClient("edex-cloud.unidata.ucar.edu") + request = GetRadarDataRecordRequest() + request.setTimeRange(timerange) + request.setRadarId("klzk") + request.setProductCode("94") # N0Q + request.setPrimaryElevationAngle("0.5") + response = client.sendRequest(request) + for record in response.getData(): + # Get record hdf5 data + idra = record.getHdf5Data() + rdat,azdat,depVals,threshVals = RadarCommon.get_hdf5_data(idra) + dim = rdat.getDimension() + lat,lon = float(record.getLatitude()),float(record.getLongitude()) + radials,rangeGates = rdat.getSizes() + # Convert raw byte to pixel value + rawValue=np.array(rdat.getByteData()) diff --git a/docs/source/index.rst b/docs/source/index.rst index e4feb62..bed0c09 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,23 +2,37 @@ Python AWIPS Data Access Framework ================================== -`AWIPS `_ is a weather display and analysis package developed by the National Weather Service for operational forecasting. UCAR's `Unidata Program Center `_ supports a non-operational open-source release of the AWIPS software (`EDEX `_, `CAVE `_, and `python-awips `_). - The python-awips package provides a data access framework for requesting grid and geometry datasets from an `EDEX `_ server. +`AWIPS `_ is a weather display and analysis package developed by the National Weather Service for operational forecasting. UCAR's `Unidata Program Center `_ supports a non-operational open-source release of the AWIPS software (`EDEX `_, `CAVE `_, and `python-awips `_). + .. _Jupyter Notebook: http://nbviewer.jupyter.org/github/Unidata/python-awips/tree/master/examples/notebooks -Install -------- +Pip Install +----------- - pip install python-awips -Requirements -~~~~~~~~~~~~ +Conda Environment Install +------------------------- + +To install the latest version of python-awips, with all required and optional packages: + +- git clone https://github.com/Unidata/python-awips.git +- cd python-awips +- conda env create -f environment.yml +- source activate python-awips +- python setup.py install --force +- jupyter notebook examples + +Requirements +------------ + +- python 2.7+ +- numpy +- shapely +- six -- Python 2.7+ -- Shapely 1.4+ -- MetPy and enum34 to run the `Jupyter Notebook`_ examples Quick Example ~~~~~~~~~~~~~ @@ -31,29 +45,31 @@ Quick Example list(dataTypes) ['acars', - 'binlightning', - 'bufrmosavn', - 'bufrmoseta', - 'bufrmosgfs', - 'bufrmoshpc', - 'bufrmoslamp', - 'bufrmosmrf', - 'bufrua', - 'climate', - 'common_obs_spatial', - 'gfe', - 'grid', - 'hydro', - 'maps', - 'modelsounding', - 'obs', - 'practicewarning', - 'radar', - 'radar_spatial', - 'satellite', - 'sfcobs', - 'topo', - 'warning'] + 'binlightning', + 'bufrmosavn', + 'bufrmoseta', + 'bufrmosgfs', + 'bufrmoshpc', + 'bufrmoslamp', + 'bufrmosmrf', + 'bufrua', + 'climate', + 'common_obs_spatial', + 'gfe', + 'gfeeditarea', + 'grid', + 'maps', + 'modelsounding', + 'obs', + 'practicewarning', + 'profiler', + 'radar', + 'radar_spatial', + 'satellite', + 'sfcobs', + 'topo', + 'warning'] + request = DataAccessLayer.newDataRequest() request.setDatatype("satellite") @@ -91,15 +107,15 @@ Quick Example See the `API Documentation `_ for more information. -------------- -Documentation -------------- +---------------------- +Read The Docs Contents +---------------------- .. toctree:: :maxdepth: 2 - install api/index + datatypes examples/index dev gridparms diff --git a/docs/source/install.rst b/docs/source/install.rst deleted file mode 100644 index 3a36ebc..0000000 --- a/docs/source/install.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _Jupyter Notebook: http://nbviewer.jupyter.org/github/Unidata/python-awips/tree/master/examples/notebooks - -Installation ------------------- - -- pip install python-awips - -Requirements -~~~~~~~~~~~~ - -- Python 2.7 or later -- pip install numpy shapely -- pip install metpy enum34 - to run `Jupyter Notebook`_ examples - -Install from Github -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- git clone https://github.com/Unidata/python-awips.git && cd python-awips -- python setup.py install - - -Install for AWIPS -~~~~~~~~~~~~~~~~~ - -On standalone AWIPS systems, the full `AWIPS Python Stack `_ is installed to ``/awips2/python`` as RPM packages. - -Easy install on an AWIPS system - -* For Unidata AWIPS release **16.2.2+**: - - * /awips2/python/bin/easy_install pip - * /awips2/python/bin/pip install python-awips - -* For releases before and up to **16.1.5** you may need to run - - * yum install awips2-python-setuptools -