{"id":29482853,"url":"https://github.com/lnferris/ocean_data_tools","last_synced_at":"2025-07-15T02:02:27.177Z","repository":{"id":56575305,"uuid":"140592821","full_name":"lnferris/ocean_data_tools","owner":"lnferris","description":"A MATLAB toolbox for interacting with bulk freely-available oceanographic data.","archived":false,"fork":false,"pushed_at":"2022-02-23T15:02:20.000Z","size":40565,"stargazers_count":96,"open_issues_count":6,"forks_count":27,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-08T02:17:30.717Z","etag":null,"topics":["argo-floats","hycom","matlab","ocean","ocean-data","oceanography","physical-oceanography"],"latest_commit_sha":null,"homepage":"","language":"MATLAB","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/lnferris.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-11T15:11:46.000Z","updated_at":"2025-07-01T18:54:41.000Z","dependencies_parsed_at":"2022-08-15T21:20:09.693Z","dependency_job_id":null,"html_url":"https://github.com/lnferris/ocean_data_tools","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/lnferris/ocean_data_tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnferris%2Focean_data_tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnferris%2Focean_data_tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnferris%2Focean_data_tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnferris%2Focean_data_tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lnferris","download_url":"https://codeload.github.com/lnferris/ocean_data_tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lnferris%2Focean_data_tools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264357172,"owners_count":23595569,"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":["argo-floats","hycom","matlab","ocean","ocean-data","oceanography","physical-oceanography"],"created_at":"2025-07-15T02:01:57.009Z","updated_at":"2025-07-15T02:02:27.153Z","avatar_url":"https://github.com/lnferris.png","language":"MATLAB","readme":"# ocean_data_tools: a MATLAB toolbox for interacting with bulk freely-available oceanographic data\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/85356569-4664ba80-b4dd-11ea-9ec7-8ec26df76dcf.png\" width=\"500\"\u003e\n\n[![GitHub license](https://img.shields.io/github/license/lnferris/ocean_data_tools)](https://github.com/lnferris/ocean_data_tools/blob/master/LICENSE) [![GitHub stars](https://img.shields.io/github/stars/lnferris/ocean_data_tools)](https://github.com/lnferris/ocean_data_tools/stargazers) [![GitHub forks](https://img.shields.io/github/forks/lnferris/ocean_data_tools)](https://github.com/lnferris/ocean_data_tools/network) \n[![View ocean_data_tools on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/80047-ocean_data_tools) [![DOI](https://joss.theoj.org/papers/10.21105/joss.02497/status.svg)](https://doi.org/10.21105/joss.02497)\n\n**Copyright (c) 2020 lnferris** \n\nocean_data_tools simplifies the process of extracting, formatting, and visualizing freely-available oceanographic data. While a wealth of oceanographic data is accessible online, some end-users may be dissuaded from utilizing this data due to the overhead associated with obtaining and formatting it into usable data structures. ocean_data_tools solves this problem by allowing the user to transform common oceanographic data sources into uniform structs, call generalized functions on these structs, easily perform custom calculations, and make graphics.\n\nFind a bug, have a question, or want to chat about contributing? Open an issue or email lnferris@alum.mit.edu.\n\n### [Getting Started](#getting-started-1)\n\n### [Dependencies](#dependencies-1)\n\n### [Accessing Help](#accessing-help-1)\n\n### [How to Contribute](#how-to-contribute-1)\n\n### [Contents](#contents-1)\n\n### [Finding Data](#finding-data-1)\n\n### [Citing ODT](#citing-odt-1)\n\n## Getting Started\n\n1. Download [bathymetry](#bathymetry).\n2. Download [nctoolbox](https://github.com/nctoolbox/nctoolbox). You will need to run the command ``setup_nctoolbox`` at the beginning of each MATLAB session.\n3. Add ocean_data_tools and nctoolbox to the path. Specifically, the following folders must be added to the [path](https://www.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html):\n\n- ocean_data_tools/ocean_data_tools\n- ocean_data_tools/ocean_data_tools/utilities\n- nctoolbox/\n\n4. Run each demonstration in **demos/demos.m**, which contains example usages for all functions. All required test data is included in **data/**.\n\nFunctions are named using a two-part system. The prefix (``argo_``, ``bathymetry_``, ``general_``, etc.) indicates the appropriate data source, while the suffix (``\\_build``, ``\\_profiles``, ``\\_section``, etc.) indicates the action performed. Functions with the ``\\_build`` suffix load raw data into uniform structs (e.g. ``argo``, ``cruise``, ``hycom``, ``mercator``, ``woa``, ``wod``). Uniform structs created by ``\\_build`` functions are compatable with any ``general_`` function.\n\nData sources currently supported:\n| Data Source | DOI, Product Code, or Link    |\n|:--  |:--|\n| Argo floats | [doi:10.17882/42182](https://doi.org/10.17882/42182) |\n| Smith \u0026 Sandwell bathymetry | [doi:10.1126/science.277.5334.1956](https://doi.org/10.1126/science.277.5334.1956) |\n| IOOS Glider DAC | https://gliders.ioos.us/ |\n| MOCHA Climatology | [doi:10.7282/T3XW4N4M](https://doi.org/10.7282/T3XW4N4M) |\n| HYbrid Coordinate Ocean Model | https://hycom.org |\n| CMEMS Global Ocean 1/12° Physics Analysis and Forecast | GLOBAL_ANALYSIS_FORECAST_ PHY_001_024 |\n| CMEMS Global Ocean Waves Multi Year | GLOBAL_REANALYSIS_WAV_001_032 |\n| GO-SHIP hydrographic cruises | https://www.go-ship.org/ |\n| World Ocean Atlas 2018 | https://www.ncei.noaa.gov/products/world-ocean-atlas |\n| World Ocean Database | https://www.ncei.noaa.gov/products/world-ocean-database |\n\nMain functions are located in **ocean_data_tools/**. Demonstrations are located in **demos/**. Test datas are located in **data/**. Shell scripts for batch downloading data are located in **shell_scripts/**. While shell scripts can be run directly in a macOS Terminal, running them in Windows requires [Cygwin](https://www.cygwin.com/) (and perhaps slight modification of commands). Python syntax examples are located in **python/**, which may be grow to become a module in the future.\n\n## Dependencies\n\nThe only true dependency is [nctoolbox](https://github.com/nctoolbox/nctoolbox).\n\nIt is recommended to also download [Gibbs-SeaWater (GSW) Oceanographic Toolbox](http://www.teos-10.org/software.htm#1). A benefit of ocean_data_tools is that neatly packs data into uniform structs; at which point a user can easily apply custom calculations or functions from other toolboxes such as GSW. See an [example](docs/gsw_example.md).\n\n## Accessing Help\n\nTo access help, run the command ``doc ocean_data_tools``.\n\n## How to Contribute\n\n* Want to make changes or add a new function? (1) Fork the repository (make your own separate copy), (2) make changes, and (3) open a 'pull request'. Once approved, it can be merged into the master branch. If you wish to chat beforehand about your contribution, open an issue or email lnferris@alum.mit.edu. \n* Don't use git often and don't want to remember all the terminal commands? Download [GitHub Desktop](https://desktop.github.com/).\n* Find a bug in the code? Open an 'issue' to notify contributors and create an official record.\n\nBefore contributing, please see [Contents](#contents-1) and consider how your function fits into ocean_data_tools and its ethos of structure arrays. At a minimum, functions must be well-documented and address a specific freely-available oceanographic data source which can be accessed by anyone online.\n\nAdding a new function isn't the only way to contribute. Python, Julia, etc. translations of existing Matlab functions are also welcomed!\n\nIf you are interested in becoming a formal collaborator (e.g. have direct access and co-manage this repository), please reach out.\n\n## Contents\n\n#### [Building uniform structs from data sources](#building-uniform-structs-from-data-sources-1)\n\n#### [General functions for subsetting and plotting uniform structs](#general-functions-for-subsetting-and-plotting-uniform-structs-1)\n\n#### [Plotting gridded data without building structs](#plotting-gridded-data-without-building-structs-1)\n\n#### [Adding bathymetry to existing plots](#adding-bathymetry-to-existing-plots-1)\n\n#### [Additional functions for inspecting Argo data](#additional-functions-for-inspecting-argo-data-1)\n\n#### [Miscellaneous utilities](#miscellaneous-utilities-1)\n\n\n### Building uniform structs from data sources\n\n**[argo_build](docs/argo_build.md)** searches the locally-stored Argo profiles matching the specified region \u0026 time period and builds a uniform struct\n\n**[glider_build](docs/glider_build.md)** loads an archived glider survey (downloaded from gliders.ioos.us/erddap) and builds a uniform struct\n\n**[mocha_build_profiles](docs/mocha_build_profiles.md)** builds a uniform struct of profiles from the MOCHA Mid-Atlantic Bight climatology\n\n**[model_build_profiles](docs/model_build_profiles.md)**  builds a uniform struct of profiles from HYCOM or Operational Mercator CMEMS GLOBAL_ANALYSIS_FORECAST_PHY_001_024\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/88250150-ac776580-cc74-11ea-8c72-cea7cc50b4d9.png\" width=\"700\"\u003e\n\n**waves_build** builds a uniform struct of timeseries from CMEMS Global Ocean Waves Multi Year product GLOBAL_REANALYSIS_WAV_001_032\n\n**[whp_cruise_build](docs/whp_cruise_build.md)** builds a uniform struct of profiles from GO-SHIP cruise data in WHP-Exchange Format\n\n**[woa_build_profiles](docs/woa_build_profiles.md)** builds a uniform struct of profiles from World Ocean Atlas 2018 Statistical Mean for All Decades, Objectively Analyzed Mean Fields\n\n**[wod_build](docs/wod_build.md)** builds a uniform struct of profiles from World Ocean Database data\n\n*Don't see a function yet for your preferred data source? Email lnferris@alum.mit.edu to request or [contribute](#how-to-contribute-1).*\n\n### General functions for subsetting and plotting uniform structs\n\n**[general_depth_subset](docs/general_depth_subset.md)** subsets a uniform struct by depth\n\n**[general_map](docs/general_map.md)** plots coordinate locations in a uniform struct, with optional bathymetry contours\n\n**[general_profiles](docs/general_profiles.md)** plots vertical profiles in a uniform struct\n\n**[general_region_subset](docs/general_region_subset.md)** subsets a uniform struct by polygon region\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/88250944-358f9c00-cc77-11ea-9b0d-2d582ad186dd.png\" width=\"700\"\u003e\n\n**[general_remove_duplicates](docs/general_remove_duplicates.md)** removes spatially (or spatially and temporally) non-unique profiles from a uniform struct\n\n**[general_section](docs/general_section.md)** plots a data section from a uniform struct\n\n\n### Plotting gridded data without building structs\n\n**[mocha_domain_plot](docs/mocha_domain_plot.md)** plots a 3-D domain from the MOCHA Mid-Atlantic Bight climatology\n\n**[mocha_simple_plot](docs/mocha_simple_plot.md)** plots a 2-D layer from the MOCHA Mid-Atlantic Bight climatology\n\n**[model_domain_plot](docs/model_domain_plot.md)** plots a 3-D domain from HYCOM or Operational Mercator CMEMS GLOBAL_ANALYSIS_FORECAST_PHY_001_024\n\n**[model_simple_plot](docs/model_simple_plot.md)** plots a 2-D layer from HYCOM or Operational Mercator CMEMS GLOBAL_ANALYSIS_FORECAST_PHY_001_024\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/88250403-8900ea80-cc75-11ea-8a5d-8a474d2e5c3f.png\" width=\"700\"\u003e\n\n**[woa_domain_plot](docs/woa_domain_plot.md)** plots a 3-D domain from World Ocean Atlas 2018 Statistical Mean for All Decades, Objectively Analyzed Mean Fields\n\n**[woa_simple_plot](docs/woa_simple_plot.md)** plots a 2-D layer from World Ocean Atlas 2018 Statistical Mean for All Decades, Objectively Analyzed Mean Fields\n\n### Adding bathymetry to existing plots\n\n**[bathymetry_extract](docs/bathymetry_extract.md)** extracts a region of Smith \u0026 Sandwell Global Topography and outputs as arrays\n\n**[bathymetry_plot](docs/bathymetry_plot.md)** adds bathymetry to 2-D (latitude vs. longitude) or 3-D (latitude vs. longitude vs. depth) data plots\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/88251161-ed24ae00-cc77-11ea-87d6-0e3b4484764d.jpg\" width=\"700\"\u003e\n\n**[bounding_region](docs/bounding_region.md)** finds the rectangular region around a uniform struct and/or list of coordinates to pass as an argument for other bathymetry functions\n\n**[bathymetry_section](docs/bathymetry_section.md)** adds Smith \u0026 Sandwell Global Topography to a section from plot using bathymetry data nearest to specified coordinates\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/88250660-3d027580-cc76-11ea-808c-f51d5105e420.png\" width=\"700\"\u003e\n\n### Additional functions for inspecting Argo data\n\n**[argo_platform_map](docs/argo_platform_map.md)** plots locations of Argo profiles in a uniform struct, coloring markers by platform (individual Argo float)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/88250439-a2099b80-cc75-11ea-9516-ad3d1f65fdf9.jpg\" width=\"700\"\u003e\n\n**[argo_platform_subset](docs/argo_platform_subset.md)** subsets a uniform struct of Argo data to one platform (individual Argo float)\n\n**[argo_profiles_map](docs/argo_profiles_map.md)** plots coordinate locations of Argo profiles in uniform struct argo, using colors corresponding to argo_profiles called on the same struct\n\n**[argo_profiles](docs/argo_profiles.md)** plots vertical Argo profiles in uniform struct argo, using colors corresponding to argo_profiles_map called on the same struct\n\n\n### Miscellaneous utilities\n\n**[region_select](docs/region_select.md)** creates coordinate list (which represents vertices of a polygon region) by clicking stations on a plot\n\n**[transect_select](docs/transect_select.md)** creates a coordinate list (which represents a virtual transect) by clicking stations on a plot\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/88250639-2b20d280-cc76-11ea-9c94-3ce16300f735.png\" width=\"700\"\u003e\n\n\n## Finding Data\n\nThere two types of datasets: those that need to be downloaded manually\u003csup\u003e1\u003c/sup\u003e and those that can be accessed remotely\u003csup\u003e2\u003c/sup\u003e through OpenDAP (e.g. the data can be accessed directly on the the internet using a url). \n\n#### argo\u003csup\u003e1\u003c/sup\u003e\n\nDownload [Argo data](https://argo.ucsd.edu/) directly from GDAC FTP servers using either the [Coriolis selection tool](http://www.argodatamgt.org/Access-to-data/Argo-data-selection), or the [US GDAC](https://nrlgodae1.nrlmry.navy.mil/cgi-bin/argo_select.pl). See the [Argo User's Manual](http://www.argodatamgt.org/Documentation) for more information.\n\nAlternatively run **shell_scripts/download_argo** to download data via File Transfer Protocol.\n\n#### bathymetry\u003csup\u003e1\u003c/sup\u003e\n\nTo get bathymetry data (for ``bathymetry_dir``), download Smith \u0026 Sandwell under [Global Topography V19.1](https://topex.ucsd.edu/marine_topo/) in netcdf form (topo_20.1.nc).\n\n#### glider\u003csup\u003e1\u003c/sup\u003e\n\nVist [gliders.ioos.us/erddap](https://gliders.ioos.us/erddap/index.html). Click \"View a List of All 779 Datasets\" or use the \"Advanced Search\". After choosing a dataset, navigate to the [Data Access Form](https://gliders.ioos.us/erddap/tabledap/ce_311-20170725T1930-delayed.html). To get started, select these variables:\n\n\u003cimg src=\"https://user-images.githubusercontent.com/24570061/94058620-419af580-fdaf-11ea-859a-616c8b5b1433.png\" width=\"700\"\u003e\n\nScroll to \"File type:\". In the drop-down menu, select \".nc\". Click \"Submit\".\n\n#### mocha\u003csup\u003e2\u003c/sup\u003e\n\nThe url for MOCHA Mid-Atlantic Bight climatology is embedded. See [Rutgers Marine catalog](http://tds.marine.rutgers.edu/thredds/catalog.html).\n\n#### model\u003csup\u003e1,2\u003c/sup\u003e\n\nHYCOM data may be accessed remotely using OpenDAP. Get the data url by visiting the [HYCOM website](https://www.hycom.org/dataserver/gofs-3pt1/analysis). For example, click Access Data Here -\u003e GLBv0.08/expt_57.7 (Jun-01-2017 to Sep-30-2017)/ -\u003e Hindcast Data: Jun-01-2017 to Sep-30-2017. Click on the OpenDAP link. Copy the url as and use this as the ``source`` in ``model_build_profiles``.\n\nAlteratively, download subsetted HYCOM data using NCSS. Get the data url by visiting the [HYCOM website](https://www.hycom.org/dataserver/gofs-3pt1/analysis). For example, click Access Data Here -\u003e GLBv0.08/expt_57.7 (Jun-01-2017 to Sep-30-2017)/ -\u003e Hindcast Data: Jun-01-2017 to Sep-30-2017. Click on the NetcdfSubset link. Set constraints and copy the NCSS Request URL at the bottom of the page. Run **shell_scripts/download_hycom_lite**. To download multiple months or years, run **shell_scripts/download_hycom_bulk_daily** (partition files by day) or **shell_scripts/download_hycom_bulk_monthly** (partition files by month). Please use responsibly.\n\nFor Mercator, download Copernicus Marine data directly from FTP servers. First make a [Copernicus account](http://marine.copernicus.eu/services-portfolio/access-to-products/). Use the selection tool to download GLOBAL_ANALYSIS_FORECAST_PHY_001_024. Alternatively run **shell_scripts/download_mercator**. Before running the script, follow the instructions for modifying your ~/.netrc file in the comments of the script.\n\n#### waves\u003csup\u003e1\u003c/sup\u003e\n\nFirst make a [Copernicus account](http://marine.copernicus.eu/services-portfolio/access-to-products/). Use the selection tool to download CMEMS Global Ocean Waves Multi Year product GLOBAL_REANALYSIS_WAV_001_032.\n\n#### whp_cruise\u003csup\u003e1\u003c/sup\u003e\n\nFor [GO-SHIP data](https://usgoship.ucsd.edu/hydromap/), get CTD data (for ``ctdo_dir``) by choosing a [GO-SHIP cruise](https://cchdo.ucsd.edu/search?q=GO-SHIP) and downloading the CTD data in whp_netcdf format. More information about whp_netcdf parameters is available [here](https://exchange-format.readthedocs.io/en/latest/index.html#). Get LADCP data (for ``uv_dir``, ``wke_dir``) [here](https://currents.soest.hawaii.edu/go-ship/ladcp/). There is information about LACDP processing [here](https://www.ldeo.columbia.edu/~ant/LADCP.html).\n\n#### woa\u003csup\u003e2\u003c/sup\u003e\n\nFunctions build the World Ocean Atlas url at maximum resolution based on arguments, but coarser resolutions and seasonal climatologies are available at the [NODC website](https://www.nodc.noaa.gov/OC5/woa18/woa18data.html). Note NCEI is scheduled to update data urls in the near future. Functions will be updated as such.\n\n#### wod\u003csup\u003e1\u003c/sup\u003e\n\nSearch the [World Ocean Database](https://www.nodc.noaa.gov/OC5/SELECT/dbsearch/dbsearch.html) and select products.\n\n## Citing ODT\n\nFerris, L., (2020).  ocean_data_tools:  A MATLAB toolbox for interacting with bulk freely-available oceanographic data. Journal of Open Source Software, 5(54), 2497. https://doi.org/10.21105/joss.02497\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnferris%2Focean_data_tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flnferris%2Focean_data_tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flnferris%2Focean_data_tools/lists"}