{
"info": {
"author": "Erin Nagel, Jason Greenlaw",
"author_email": "erin.nagel@noaa.gov, jason.greenlaw@noaa.gov",
"bugtrack_url": null,
"classifiers": [
"Intended Audience :: Science/Research",
"License :: OSI Approved :: BSD License",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3"
],
"description": "thyme\n=====\n\n**T**ools for **Hy**drodynamic **M**odel Output **E**xtraction\n\nA Python package providing utilities for processing, interpolating, and\nconverting hydrodynamic ocean model NetCDF datasets.\n\nWhy?\n----\n\nThere are many hydrodynamic modeling frameworks in use today by the\noceanographic community. All models are output to a NetCDF format, but\nthe structure, dimensions, variables, attributes, naming conventions,\ncoordinate systems, and masking rules can all vary significantly, making\nit difficult for users to extract meaningful information from these\ncomplex systems.\n\nThis package attempts to support a common methodology for interacting\nwith these datasets by abstracting the nuances of each modeling system\ninto distinct modules and unifying them with a single API.\n\nSupported Models\n----------------\n\n*NOTE: To date, this package has been tested to work with National Ocean\nService (NOS) Operational Forecast Systems (OFS) (e.g. CBOFS, DBOFS,\nNGOFS, etc.), however with minor tweaks it should also work with output\nfrom non-NOS OFS models.*\n\nThe following ocean modeling frameworks are presently supported:\n\n**Regional Ocean Modeling System (ROMS)**\n\n> *\\\"ROMS is a free-surface, terrain-following, primitive equations\n> ocean model widely used by the scientific community for a diverse\n> range of applications\\...In the horizontal, the primitive equations\n> are evaluated using boundary-fitted, orthogonal curvilinear\n> coordinates on a staggered Arakawa C-grid. The general formulation of\n> curvilinear coordinates includes both Cartesian (constant metrics) and\n> spherical (variable metrics) coordinates. Coastal boundaries can also\n> be specified as a finite-discretized grid via land/sea masking. As in\n> the vertical, the horizontal stencil utilizes a centered, second-order\n> finite differences.\\\"*\n>\n> Description from \n\n**Finite-Volume Community Ocean Modeling System (FVCOM)**\n\n> *\\\"FVCOM is a prognostic, unstructured-grid, finite-volume,\n> free-surface, 3-D primitive equation coastal ocean circulation model\n> developed by UMASSD-WHOI joint efforts. The model consists of\n> momentum, continuity, temperature, salinity and density equations and\n> is closed physically and mathematically using turbulence closure\n> submodels. The horizontal grid is comprised of unstructured triangular\n> cells and the irregular bottom is presented using generalized\n> terrain-following coordinates.\\\"*\n>\n> Description from \n\n**Princeton Ocean Model (POM)**\n\n> *\\\"POM is a sigma coordinate (terrain-following), free surface ocean\n> model with embedded turbulence and wave sub-models, and wet-dry\n> capability.\\\"*\n>\n> Description from \n\n**Hybrid Coordinate Ocean Model (HYCOM)**\n\n> *\\\"The HYbrid Coordinate Ocean Model is a primitive equation ocean\n> general circulation model that evolved from the Miami\n> Isopycnic-Coordinate Ocean Model (MICOM) developed by Rainer Bleck and\n> colleagues. Vertical coordinates in HYCOM remain isopycnic in the\n> open, stratified ocean. However, they smoothly transition to z\n> coordinates in the weakly-stratified upper-ocean mixed layer, to\n> terrain-following sigma coordinate in shallow water regions, and back\n> to level coordinates in very shallow water.\\\"*\n>\n> Description from \n\nAdditionally, a generic `rectilinear` module has been created to support\nany model output whose coordinate system conforms to a rectilinear grid\nand whose depth coordinates reflect standard depths/z-levels, however\nthis module does not support vertical interpolation.\n\nFeatures\n--------\n\n- Support for ROMS, FVCOM, POM, HYCOM model output\n- Interpolate staggered horizontal coordinates (i.e. ROMS Arakawa-C\n grid rho/eta/xi) to common coordinates before further processing\n- Apply spatially-varying rotation angle to u/v current components to\n obtain true-north/true-east values before further processing\n- Interpolate sigma (bathymetry-following) vertical coordinates to a\n given depth-below-surface, respecting the appropriate vertical\n transformation, if any\n- Given an approximate target grid resolution, generate a regular grid\n definition conforming to the model domain\\'s bounding box (or\n optionally to a predefined set of bounding rectangles), and output\n regular grid definition to CF-compliant NetCDF\n\nIndex (Grid Definition) Files\n-----------------------------\n\nIn order to convert model output files to a regular grid, an index file\nmust be supplied at runtime. The purpose of the index file is to persist\ninformation that does not change between model runs in order to reduce\nthe overall processing time per cycle run. The information stored in the\nindex file includes the output grid definition and general metadata\nabout the model itself. Index files for FVCOM-based models with a hybrid\n(generalized) coordinate system additionally store interpolated vertical\ncoordinate values for each output grid cell.\n\nWhen generating a grid definition, the user has a choice between using\nthe full extent of the model\\'s domain or supplying a shapefile\ncontaining one or more polygons defining subgrids\n(sub-regions/subdomains) to which the grid definition will conform. If\nno subgrid shapefile is specified, the resulting index file will define\na regular grid (with NoData mask) matching the full model domain\n(extent). Otherwise, if a subgrid shapefile is specified, the resulting\nindex file will define a regular grid (with NoData mask) matching the\nunified extent of all subgrid polygons that intersect the model domain,\nalong with information identifying the grid cell ranges that correspond\nwith each subgrid. Note that when supplying a subgrid shapefile, all\nsubgrid polygons must be rectangular, congruent with each other, and\nadjacent to one another.\n\nA subgrid index is intended to be used to subset the model output into\nsmaller geographic areas (i.e. tiles), which in turn results in smaller\noutput file sizes. Optionally, for a subgrid index file, the user may\nspecify the name of an attribute field within the subgrid shapefile that\nuniquely identifies each subgrid (tile). If no field is specified, each\npolygon\\'s FID value is used as the identifier. This identifier can be\nused to construct unique filenames.\n\nAdditionally, a land mask polygon shapefile can be supplied when\ngenerating an index file. If supplied, any output grid cells whose\ncentroid intersects a land polygon will be masked in the final grid\ndefinition.\n\nOne index file must be created per ocean forecast system for each\ncombination of target resolution and extent (whether using the model\\'s\nfull domain extent or subgrid definition).\n\nWhen to Generate a New Index File\n---------------------------------\n\nOnce a model index file is created, it can be reused indefinitely for\nthat model/resolution/extent/land mask until any of those properties\nchange. For example, if an FVCOM-based model has a hybrid (generalized)\nvertical coordinate system that is modified at some point (i.e., sigma\nvalues are changed), any associated index files will need to be\nregenerated using a new model output file in the updated format.\n\nGenerally, a new index file is required:\n\n- For each new model\n- For each desired output grid resolution\n- For each desired set of subgrids\n- If the subgrid polygons change\n- If the subgrid attribute identifier changes\n- If the land mask shapefile changes\n- If the underlining model changes (e.g., new geographic extent,\n change to FVCOM sigma coordinates, etc.)\n\nRequirements\n------------\n\nThis codebase is written for Python 3 and relies on the following python\npackages:\n\n- gdal\n- netCDF4\n- numpy\n- scipy\n- shapely\n\nInstallation\n------------\n\nThe GDAL Python bindings used by this package require system libraries to be\npresent, so it usually can\\'t just be installed using `pip install gdal`.\nWe recommend installing GDAL either through a package manager (e.g.\n`conda`, `apt`, `yum`, `pacman`) or by compiling from scratch.\n[Miniconda](https://docs.conda.io/en/latest/miniconda.html) is probably\nthe easiest method.\n\nOnce `gdal` has been installed, thyme can be installed using `pip`:\n\n```python\npip install thyme\n```\n\nExample Usage\n-------------\n\nTo generate a new index file for an FVCOM-based model using the default\ngrid extent, a \\~500 meter target resolution, and a shoreline shapefile\ndefining land areas to be masked:\n\n```python\nfrom thyme.model import fvcom\nnative_model_file = fvcom.FVCOMFile('/path/to/existing_fvcom_file.nc')\nmodel_index_file = fvcom.FVCOMIndexFile('/path/to/new_index_file.nc')\ntry:\n native_model_file.open()\n model_index_file.open()\n model_index_file.init_nc(native_model_file, 500, 'my_fvcom_model', '/path/to/shoreline_shapefile.shp')\nfinally:\n model_index_file.close()\n native_model_file.close()\n```\n\nTo generate a new index file for a ROMS-based model using a subgrid\nshapefile (with fieldname 'id' used to identify subgrid areas) and a\n\\~300m target resolution (with no shoreline mask shapefile specified):\n\n```python\nfrom thyme.model import roms\nnative_model_file = roms.ROMSFile('/path/to/existing_roms_file.nc')\nmodel_index_file = roms.ROMSIndexFile('/path/to/new_index_file.nc')\ntry:\n native_model_file.open()\n model_index_file.open()\n model_index_file.init_nc(native_model_file, 300, 'my_roms_model', None, '/path/to/subgrid_shapefile.shp', 'subgrid_id_fieldname')\nfinally:\n model_index_file.close()\n native_model_file.close()\n```\n\nTo interpolate u/v current components from a ROMS-based model to a\nregular grid defined in an existing model index file, at a depth of 4.5\nmeters below surface, for time index 0, and store the resulting u/v\nvalues in two `numpy.ma.masked_array` objects:\n\n```python\nfrom thyme.model import roms\nnative_model_file = roms.ROMSFile('/path/to/existing_roms_file.nc')\nmodel_index_file = roms.ROMSIndexFile('/path/to/existing_index_file.nc')\ntry:\n native_model_file.open()\n model_index_file.open()\n (u_with_mask, v_with_mask) = native_model_file.uv_to_regular_grid(model_index_file, 0, 4.5)\n # u_with_mask and v_with_mask now contain 2D numpy masked arrays\nfinally:\n model_index_file.close()\n native_model_file.close()\n```\n\nAuthors\n-------\n\n- Erin Nagel (UCAR), \n- Jason Greenlaw (ERT), \n\nLicense\n-------\n\nThis work, as a whole, is licensed under the BSD 2-Clause License (see\n[LICENSE](LICENSE)), however it contains major contributions from the\nU.S. National Oceanic and Atmospheric Administration (NOAA), 2017 -\n2019, which are individually dedicated to the public domain.\n\nDisclaimer\n----------\n\nThis repository is a scientific product and is not official\ncommunication of the National Oceanic and Atmospheric Administration, or\nthe United States Department of Commerce. All NOAA GitHub project code\nis provided on an \\\"as is\\\" basis and the user assumes responsibility\nfor its use. Any claims against the Department of Commerce or Department\nof Commerce bureaus stemming from the use of this GitHub project will be\ngoverned by all applicable Federal law. Any reference to specific\ncommercial products, processes, or services by service mark, trademark,\nmanufacturer, or otherwise, does not constitute or imply their\nendorsement, recommendation or favoring by the Department of Commerce.\nThe Department of Commerce seal and logo, or the seal and logo of a DOC\nbureau, shall not be used in any manner to imply endorsement of any\ncommercial product or activity by DOC or the United States Government.\n\nAcknowledgments\n---------------\n\nThis software has been developed by the National Oceanic and Atmospheric\nAdministration (NOAA)/National Ocean Service (NOS)/Office of Coast\nSurvey (OCS)/Coast Survey Development Lab (CSDL) for use by the\nscientific and oceanographic communities.\n\nCSDL wishes to thank the following entities for their assistance:\n\n- NOAA/NOS/Center for Operational Oceanographic Products and Services\n (CO-OPS)\n- Canadian Hydrographic Service (CHS)\n- Teledyne CARIS\n\n\n",
"description_content_type": "text/markdown",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/noaa-ocs-modeling/thyme",
"keywords": "",
"license": "BSD-2-Clause",
"maintainer": "",
"maintainer_email": "",
"name": "thyme",
"package_url": "https://pypi.org/project/thyme/",
"platform": "",
"project_url": "https://pypi.org/project/thyme/",
"project_urls": {
"Homepage": "https://github.com/noaa-ocs-modeling/thyme"
},
"release_url": "https://pypi.org/project/thyme/0.3.4/",
"requires_dist": [
"shapely",
"numpy",
"scipy",
"netCDF4",
"gdal"
],
"requires_python": "",
"summary": "Tools for Hydrodynamic Model Output Extraction and Processing",
"version": "0.3.4"
},
"last_serial": 5602209,
"releases": {
"0.3.3": [
{
"comment_text": "",
"digests": {
"md5": "036e2189d3813ff66e71c8d11f8468a6",
"sha256": "812943ca273bc74020da8828d0d32e66661993c0c4daf145965aa51c2e0e3a64"
},
"downloads": -1,
"filename": "thyme-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "036e2189d3813ff66e71c8d11f8468a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 40084,
"upload_time": "2019-07-29T21:27:44",
"url": "https://files.pythonhosted.org/packages/fe/1c/724d5df1b443bfeb3c0a66533140ad76f9e252811245b687a37eb07558b7/thyme-0.3.3-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "8c24d5ec13fc020bf344392c797ab636",
"sha256": "503f732b9b23d200199fac191c5a9cf5cb326e1503ad91bb8fbc5b0b0f99c1d6"
},
"downloads": -1,
"filename": "thyme-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "8c24d5ec13fc020bf344392c797ab636",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26642,
"upload_time": "2019-07-29T21:27:46",
"url": "https://files.pythonhosted.org/packages/9b/22/d70121e6c9daed3b7ee905f1c4fd9353787ffe0288b122d5b7492199060c/thyme-0.3.3.tar.gz"
}
],
"0.3.4": [
{
"comment_text": "",
"digests": {
"md5": "b0d0db88e7bc8f62b24f2e9f66e0ac94",
"sha256": "e3950aff820bf52dcc1982d729779ec1963f9b2947fc019b6aebcf93ae31b0e4"
},
"downloads": -1,
"filename": "thyme-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0d0db88e7bc8f62b24f2e9f66e0ac94",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 40112,
"upload_time": "2019-07-29T22:13:28",
"url": "https://files.pythonhosted.org/packages/42/5b/79c25054e877337108076e47304e17ade1301d1fc6468a51996e02f6c79c/thyme-0.3.4-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "5260a1a0bbb7d49b8d10e7545c3d8828",
"sha256": "2fe90b656e74742854ad643fca8def256b7115da845e979cc6aaac143a5034bc"
},
"downloads": -1,
"filename": "thyme-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "5260a1a0bbb7d49b8d10e7545c3d8828",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26687,
"upload_time": "2019-07-29T22:13:29",
"url": "https://files.pythonhosted.org/packages/7c/c0/d3fe5d05741c5110f7a5917781342970f9483a2ae9bdbf4bcd71fc3a94df/thyme-0.3.4.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "b0d0db88e7bc8f62b24f2e9f66e0ac94",
"sha256": "e3950aff820bf52dcc1982d729779ec1963f9b2947fc019b6aebcf93ae31b0e4"
},
"downloads": -1,
"filename": "thyme-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b0d0db88e7bc8f62b24f2e9f66e0ac94",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 40112,
"upload_time": "2019-07-29T22:13:28",
"url": "https://files.pythonhosted.org/packages/42/5b/79c25054e877337108076e47304e17ade1301d1fc6468a51996e02f6c79c/thyme-0.3.4-py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "5260a1a0bbb7d49b8d10e7545c3d8828",
"sha256": "2fe90b656e74742854ad643fca8def256b7115da845e979cc6aaac143a5034bc"
},
"downloads": -1,
"filename": "thyme-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "5260a1a0bbb7d49b8d10e7545c3d8828",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26687,
"upload_time": "2019-07-29T22:13:29",
"url": "https://files.pythonhosted.org/packages/7c/c0/d3fe5d05741c5110f7a5917781342970f9483a2ae9bdbf4bcd71fc3a94df/thyme-0.3.4.tar.gz"
}
]
}