{"id":29003749,"url":"https://github.com/miniufo/xvortices","last_synced_at":"2025-06-25T10:09:19.570Z","repository":{"id":115364372,"uuid":"426860265","full_name":"miniufo/xvortices","owner":"miniufo","description":"This is a package for interpolating lat/lon gridded data onto a cylindrical coordinate translating with various kinds of vortices on Earth.","archived":false,"fork":false,"pushed_at":"2022-06-17T12:10:27.000Z","size":62182,"stargazers_count":9,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-01-27T16:08:53.618Z","etag":null,"topics":["interpolation","lagrangian","mesoscale-eddies","oceanic-eddies","tropical-cyclone","vortex","vortices","xarray"],"latest_commit_sha":null,"homepage":"https://xvortices.readthedocs.io/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/miniufo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2021-11-11T03:38:45.000Z","updated_at":"2023-11-20T06:03:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"e11418ff-896c-47a9-a819-468c3c0512b3","html_url":"https://github.com/miniufo/xvortices","commit_stats":{"total_commits":14,"total_committers":1,"mean_commits":14.0,"dds":0.0,"last_synced_commit":"bcfded54e1f9fa31e75aad6200aa652f96e363fe"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/miniufo/xvortices","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miniufo%2Fxvortices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miniufo%2Fxvortices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miniufo%2Fxvortices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miniufo%2Fxvortices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/miniufo","download_url":"https://codeload.github.com/miniufo/xvortices/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miniufo%2Fxvortices/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261850321,"owners_count":23219284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["interpolation","lagrangian","mesoscale-eddies","oceanic-eddies","tropical-cyclone","vortex","vortices","xarray"],"created_at":"2025-06-25T10:09:18.130Z","updated_at":"2025-06-25T10:09:19.546Z","avatar_url":"https://github.com/miniufo.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xvortices\n\n[![DOI](https://zenodo.org/badge/426860265.svg)](https://zenodo.org/badge/latestdoi/426860265)\n![GitHub](https://img.shields.io/github/license/miniufo/xvortices)\n[![Documentation Status](https://readthedocs.org/projects/xvortices/badge/?version=latest)](https://xvortices.readthedocs.io/en/latest/?badge=latest)\n\n![cylindrical coordinate moving on earth](./pics/cylind.jpg)\n\n## 1. Introduction\n`xvortices` is a python package built on [`xarray`](http://xarray.pydata.org/en/stable/) (starts with an `x`), targeting at extracting information about moving vortices from lat/lon gridded datasets.  Moving vortices include [tornado](https://en.wikipedia.org/wiki/Tornado), [tropical cyclone](https://en.wikipedia.org/wiki/Tropical_cyclone), [extratropical cyclone](https://en.wikipedia.org/wiki/Extratropical_cyclone), [polar vortex](https://en.wikipedia.org/wiki/Polar_vortex) in the atmospheric context, as well as [mesoscale eddy](https://en.wikipedia.org/wiki/Eddy_(fluid_dynamics)) and [ocean gyre](https://en.wikipedia.org/wiki/Ocean_gyre) in the oceanic context.  These moving vortices are usually described in a moving (also known as quasi-Lagrangian) cylindrical coordinate.  As the coordinate system moves on the spherical earth as a whole, one could take a view of the vortex dynamics from a quasi-Lagrangian perspective instead of the traditional Eulerian perspective.\n\nBasically, this package would do the following jobs:\n- accept an `xarray.Dataset` (or a list of `xarray.DataArray`) as an input dataset, usually in a fashion of lat/lon grid;\n- interpolate the data onto the cylindrical coordinates once the origin of the moving coordinate is given (this is naturally done using the builtin function of `xarray`);\n- return the interpolated fields, including scalars and vectors;\n- re-project the vectors onto the azimuthal/radial directions;\n\nWith this tool, one can perform quasi-Lagrangian diagnoses of the structure, evolution, budget, intensity etc in a perspective different from the Eulerian one.\n\n![Lagrangian-view of TC](./pics/LagrangianView.gif)\n\n---\n\n## 2. How to install\n**Requirements**\n`xvortices` is developed under the environment with `numpy` (=version 1.15.4), `xarray` (=version 0.15.1), `matplotlib` (=version 3.4.3) and `cartopy` (=version 0.18.0).  Older versions of these packages are not well tested.\n\n\n**Install from github**\n```\ngit clone https://github.com/miniufo/xvortices.git\n```\n\n---\n\n## 3. Examples\n### 3.1 A moving tropical cyclone\nHere we demonstrate an application to the case of a moving tropical cyclone (TC) over the western North Pacific.  One may need [`besttracks`](https://github.com/miniufo/besttracks) to load TC best-track data and cooperate with `xvortices`:\n```python\nimport xarray as xr\nfrom xvortices import load_cylind, project_to_cylind\n\nazimNum, radiNum, radMax = 72, 31, 6\n\n# variables inside are [u, v, w, h]\ndset = xr.open_dataset('gridded.nc')\n\n# one can obtain tropical cyclone (TC) best-track\n# data from the `besttracks` package\nolon  = TC.get_as_xarray('lon') # timeseries of center longitudes\nolat  = TC.get_as_xarray('lat') # timeseries of center latitudes\nuovel = TC.get_as_xarray('uo')  # timeseries of center u-vel\nvovel = TC.get_as_xarray('vo')  # timeseries of center v-vel\n\n[u, v, w, h], lons, lats, etas = load_cylind(dset, olon=olon, olat=olat,\n                                             azimNum=azimNum, radiNum=radiNum,\n                                             radMax=radMax)\nurel = u - uovel # storm-relative u\nvrel = v - vorel # storm-relative v\n\n# storm-relative azimuthal/radial winds\nuaz, vra = project_to_cylind(urel, vrel, etas)\n```\n\n![TC example](./pics/TC.png)\n\nPlotting its 3D structure is also easy:\n```python\nfrom xvortices import plot3D\n\n# select the first time step to show\nplot3D(lons[0], lats[0], uaz[0])\n```\n\n![3D cylind](./docs/source/_static/3DCylind.png)\n\nMore details can be found at this [TC notebook](./notebooks/1.TCExample.ipynb).\n\n---\n\n### 3.2 A moving mesoscale eddy\nThis is a mesoscale eddy case over the southern Indian Ocean.\n```python\nimport pandas as pd\nimport xarray as xr\nfrom xvortices import load_cylind, project_to_cylind\n\n# load an eddy positions from the \"Mesoscale Eddy Trajectory Atlas\" product\neddy = pd.read_csv('d:/SETIO2021.txt', sep='\\s+', index_col='time', parse_dates=True)\n# load AVISO gridded sea level anomaly and associated flow\ndset = xr.open_dataset('D:/dataset-duacs-nrt-global-merged-allsat-phy-l4_SETIO_Eddy.nc')\n\n# parameters of the cylindrical coordinates\nazimNum, radiNum, radMax = 72, 31, 3\n\n# interpolate from lat/lon grid to cylindrical grid\nazimNum, radiNum, radMax = 72, 31, 4\n[sla, adt, ugos, vgos], lons, lats, etas = load_cylind(dset[['sla','adt','ugos','vgos']],\n                                             olon=eddy.lons.to_xarray(),\n                                             olat=eddy.lats.to_xarray(),\n                                             azimNum=azimNum, radiNum=radiNum,\n                                             radMax=radMax,\n                                             lonname='longitude',\n                                             latname='latitude')\n\n# calculate eddy's translating speed\nuo = (eddy['lons'].diff()/86400*np.cos(np.deg2rad(eddy['lats']))).to_xarray()\nvo = (eddy['lats'].diff()/86400).to_xarray()\n\n# calculate eddy-relative current components\nu_r = ugos - uo\nv_r = vgos - vo\n\n# project u/v to azimuthal/radial components\nuaz, vra = project_to_cylind(u_r, v_r, etas)\n```\n\n![eddy plot](./pics/eddy.png)\n\nMore details can be found at this [notebook](./notebooks/2.EddyExample.ipynb).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminiufo%2Fxvortices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminiufo%2Fxvortices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminiufo%2Fxvortices/lists"}