{ "cells": [ { "cell_type": "markdown", "id": "biological-christianity", "metadata": {}, "source": [ "\n", "(data_format)=\n", "\n", "# Data formats and access\n", "\n", "\n", "This material is from the [eReefs Data Workshop](https://ereefs.github.io/about/) - Great Barrier Reef Marine Park Authority & BOM, and the [eReefs Research](https://research.csiro.au/ereefs/) from CSIRO.\n", "\n", "> Now that you've got a bit more of a handle on how the eReefs data are generated we're going to look at how you can access them.\n", "\n", "To do this we are going to talk briefly about the data files and their structure, then give you an overview of how to access them.\n", "\n", ":::{admonition} Key outcomes:\n", ":class: important\n", "\n", "By the end of this section, you will know that:\n", "\n", "+ eReefs data uses a **netcdf** file and what that looks like.\n", "+ eReefs data can be accessed via two main ways - the **web data browser** or **Thredds/OpenDAP** protocol.\n", ":::" ] }, { "cell_type": "code", "execution_count": null, "id": "dress-kelly", "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "markdown", "id": "friendly-laugh", "metadata": {}, "source": [ "## eReefs data\n", "\n", "eReefs data is delivered through an interoperable information architecture. The system improves how data is described, discovered and accessed and adopts many of the ‘Linked Data’ principles. To find out more about Linked Data and the Semantic Web, visit https://www.w3.org/standards/semanticweb/data and http://5stardata.info/en/.\n", "\n", "\n", "### How to access eReefs data\n", "\n", "\n", "There are three ways to access eReefs data, each of which is intended for different types of users:\n", "\n", "\n", ":::{admonition} Visualisation portal\n", ":class: note, dropdown\n", "\"timeseries\"\n", "\n", "The [Visualisation Portal](https://portal.ereefs.info/) is the simplest method for most users. It provides access to any dataset which is connected to the eReefs Data Brokering Layer. For more information on how to use the portal, [click here](https://research.csiro.au/ereefs/data-visualisation/). \n", "\n", "```{note}\n", "Even though we are not going to use the portal in the course, you might want to try accessing the core data visualisation functionality with the portal following [CSIRO provided guide](https://research.csiro.au/ereefs/data-visualisation/#anchor-getting-started).\n", "```\n", "\n", "\n", "The [Time Series Extraction](https://extraction.ereefs.aims.gov.au/extract-data) tool from AIMS allows you to extract time series data for the environmental variables and locations of interest from the eReefs models in specific locations.\n", "\n", "\"timeseries\"\n", "\n", "\n", ":::\n", "\n", ":::{admonition} Data brokering layer API\n", ":class: note, dropdown\n", "\"api\"\n", "\n", "The Data Brokering Layer (DBL) API is a programmatic interface which allows developers and other technical users to discover the data services belonging to each data product. The DBL API is the front end of the [Data Brokering Layer](https://research.csiro.au/ereefs/ereefs-data/information-architecture/data-brokering-layer/), which is a collection of services and infrastructure designed to harvest information from connected Data Provider Nodes. You can access it via this [link](https://data.ereefs.info).\n", ":::\n", "\n", ":::{admonition} Direct from source\n", ":class: note, dropdown\n", "\"thredds\"\n", "\n", "Users can also find direct links to data services by using either the Visualisation Portal or the DBL API. These services can then be directly accessed from their host organisations. \n", "\n", "\n", "```{note}\n", "Users will tend to use this approach when they want to do something that the portal cannot do? This type of custom data access is the approach that we will be using for this course. \n", "\n", "```\n", ":::\n", "\n" ] }, { "cell_type": "code", "execution_count": null, "id": "exterior-possibility", "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "markdown", "id": "greater-hacker", "metadata": {}, "source": [ "## Data Access\n", "\n", "Reefs data files are stored on centralised and backed up disk at AIMS, CSIRO and BOM. These data are accessable through a series of tools that allow external users to view, query, and retrieve the data via the internet and the world wide web.\n", "\n", "### THREDDS\n", "\n", "All of the data access methods for the eReefs data are centralised around **THREDDS** (*Thematic Real-time Environmental Distributed Data Services*). **THREDDS** is middleware that bridges the gap between data providers and data users and consists of two main areas: \n", "+ the **THREDDS** Data Server (TDS) and \n", "+ the **Common Data Model (CDM)/netCDF-Java** library.\n", "\n", "\n", "```{note}\n", "**THREDDS** is developed and supported by Unidata, a division of the University Corporation for Atmospheric Research ([UCAR](http://www2.ucar.edu/)), and is sponsored by the [National Science Foundation](http://www.nsf.gov/).\n", "```\n", "\n", "### THREDDS Data Server\n", "\n", "The THREDDS Data Server (TDS) provides catalog, metadata, and data access services for scientific data. The TDS publishes [THREDDS catalogs](https://docs.unidata.ucar.edu/netcdf-java/current/userguide/index.html) that advertise the datasets and services it makes available. These THREDDS catalogs are XML documents that list the datasets and the data access services available for the eReefs system. Catalogs may contain metadata to document details about the datasets.\n", "\n", "The TDS allows users to query the datasets listed in it's catalogs using several standard data access protocols. The available remote data access protocols for eReefs include OPeNDAP, OGC WCS, OGC WMS, ERDDAP, and HTTP.\n", "\n", "The TDS also supports several dataset collection services including some sophisticated dataset aggregation capabilities. This allows the TDS to aggregate a collection of datasets into a single virtual dataset, greatly simplifying user access to that data collection. For more information see the THREDDS Data Server page.\n", "\n", "### Common Data Model\n", "\n", "The Common Data Model (CDM) provides data access through the [netCDF-Java API](https://www.unidata.ucar.edu/software/netcdf-java/) to a variety of data formats (*e.g.*, netCDF, HDF, GRIB). Layered above the basic data access, the CDM uses the metadata contained in datasets to provide a higher-level interface to geoscience specific features of datasets, in particular, providing geolocation and data subsetting in coordinate space.\n", "\n", "### OPeNDAP\n", "\n", "[OPeNDAP](http://www.opendap.org/) stands for \"Open-source Project for a Network Data Access Protocol\". OPeNDAP is both the name of a non-profit organization and the commonly-used name of a data access protocol which the OPeNDAP organization developed. The OPeNDAP protocol provides a standardised means of requesting and providing data across the World Wide Web. The goal is to allow end users, whoever they may be, to access immediately whatever data they require in a form they can use, all while using applications they already possess and are familiar with. Ultimately, it is hoped, OPeNDAP will be a fundamental component of systems which provide machine-to-machine interoperability with semantic meaning in a highly distributed environment of heterogeneous datasets.\n", "\n", "OPeNDAP allows you to access remote data over the internet using familiar data analysis and visualization packages/clients (i.e., applications able to access remote served data) like:\n", "\n", "- GIS\n", "- Python\n", "- R\n", "- Matlab\n", "- Ferret\n", "- IDL" ] }, { "cell_type": "code", "execution_count": null, "id": "cloudy-satellite", "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "markdown", "id": "excess-philadelphia", "metadata": {}, "source": [ "## Data File Structure\n", "\n", "### NetCDF\n", "\n", "\n", ":::{admonition} What do NetCDF's look like?\n", ":class: tip, dropdown\n", "\n", "**NetCDF** is a \"self-describing\" binary file format that's used a lot for storing atmospheric and oceanographic data. \n", "\n", "\"self-describing\" means that each file contains all the metadata to describe itself - *e.g.* describing the spatial and temporal dimensions of variables, as well as information about units, and what missing values are set to etc. In the beginning it's a bit of an intimidating format to deal with, but you only need to know a small subset of things to get access to the data they hold.\n", ":::\n", "\n", "\n", "\n", "\n", ":::{admonition} NetCDF files contain dimensions, variables, and attributes:\n", ":class: tip, dropdown\n", "\n", "+ A **dimension** is just a name and a size that describes what the shape of the data inside the file is.\n", "+ A **variable** has a name, a type, a list of dimensions, some attributes, and some data (As well as specific attributes attached to specific variables NetCDF files can also have some overall global attributes).\n", "+ An **attribute** has a name, a type, and a value.\n", "\n", ":::" ] }, { "cell_type": "markdown", "id": "analyzed-willow", "metadata": {}, "source": [ "### A real example\n", "\n", "```\n", "netcdf A20150521.P1D.ANN_MIM_RMP {\n", "dimensions:\n", " time = 1 ;\n", " lat = 1600 ;\n", " lon = 1400 ;\n", "variables:\n", " int time(time) ;\n", " time:long_name = \"time\" ;\n", " time:standard_name = \"time\" ;\n", " time:units = \"seconds since 1970-01-01 00:00:00\" ;\n", " time:calendar = \"gregorian\" ;\n", " time:axis = \"T\" ;\n", " time:ioos_category = \"Time\" ;\n", " float lat(lat) ;\n", " lat:long_name = \"latitude\" ;\n", " lat:standard_name = \"latitude\" ;\n", " lat:units = \"degrees_north\" ;\n", " lat:axis = \"Y\" ;\n", " lat:ioos_category = \"Location\" ;\n", " float lon(lon) ;\n", " lon:long_name = \"longitude\" ;\n", " lon:standard_name = \"longitude\" ;\n", " lon:units = \"degrees_east\" ;\n", " lon:axis = \"X\" ;\n", " lon:ioos_category = \"Location\" ;\n", " float Chl_MIM(time, lat, lon) ;\n", " Chl_MIM:_FillValue = 1.e+20f ;\n", " Chl_MIM:least_significant_digit = 3s ;\n", " Chl_MIM:comment = \"chlorophyll-a concentration, MIM SVDC on Rrs\" ;\n", " Chl_MIM:coordinates = \"time lat lon\" ;\n", " Chl_MIM:feature_id = \"http://sweet.jpl.nasa.gov/2.2/realmOcean.owl#OceanRegion\" ;\n", " Chl_MIM:ioos_category = \"Ocean Color\" ;\n", " Chl_MIM:long_name = \"chlorophyll-a concentration, MIM SVDC on Rrs\" ;\n", " Chl_MIM:matrix_id = \"http://sweet.jpl.nasa.gov/2.2/matrWater.owl#SeaWater\" ;\n", " Chl_MIM:procedure_id = \"matrix_inversion_method_singular_value_decomposition\" ;\n", " Chl_MIM:scaledQuantityKind_id = \"http://environment.data.gov.au/water/quality/def/property/chlorophyll_a_concentration\" ;\n", " Chl_MIM:standard_name = \"mass_concentration_of_chlorophyll_in_sea_water\" ;\n", " Chl_MIM:substanceOrTaxon_id = \"http://environment.data.gov.au/water/quality/def/object/chlorophyll_a\" ;\n", " Chl_MIM:unit_id = \"http://environment.data.gov.au/water/quality/def/unit/MicroGramsPerLitre\" ;\n", " Chl_MIM:units = \"mg m-3\" ;\n", " Chl_MIM:valid_max = 64.f ;\n", " Chl_MIM:valid_min = 0.f ;\n", "\n", " ...more variables here...\n", "\n", "// global attributes:\n", " :Conventions = \"CF-1.6\" ;\n", " :Metadata_Conventions = \"Unidata Dataset Discovery v1.0\" ;\n", " :Metadata_Link = \"Currently unavailable\" ;\n", " :keywords = \"EARTH SCIENCE > OCEANS > OCEAN OPTICS\" ;\n", " :keywords_vocabulary = \"NASA Global Change Master Directory (GCMD) Science Keywords\" ;\n", " :standard_name_vocabulary = \"CF-1.6\" ;\n", " :naming_authority = \"au.gov.bom\" ;\n", " :netCDF_version = \"4.1.3 of Aug 10 2011 04:46:23 \" ;\n", " :id = \"ABOM_EREEFS_MWQ_P1D_GRID_v20130813\" ;\n", " :title = \"Marine water quality grids for the Great Barrier Reef region - daily data\" ;\n", " :summary = \"Parameters calculated using the MIM SVDC on Rrs approach as part of the eReefs - Marine Water Quality project - daily data\" ;\n", " :references = \"Brando, Dekker, Park and Schroder, 2012, Adaptive semianalytical inversion of ocean color radiometry in optically complex waters, Applied Optics, v 51, n 15, 2808-2833\" ;\n", " :comment = \"NetCDF file contains water quality grids calculated using the MIM SVDC on Rrs approach for daily data\" ;\n", " :processing_level = \"Automatically generated environmental data record with quality level indicator (EDR)\" ;\n", " :cdm_data_type = \"grid\" ;\n", " :spatial_resolution = 0.01f ;\n", " :geospatial_lat_units = \"degrees_N\" ;\n", " :geospatial_lat_resolution = 0.01f ;\n", " :geospatial_lat_min = -25.495f ;\n", " :geospatial_lat_max = -9.505f ;\n", " :geospatial_lon_units = \"degrees_E\" ;\n", " :geospatial_lon_resolution = 0.01f ;\n", " :geospatial_lon_min = 142.005f ;\n", " :geospatial_lon_max = 155.995f ;\n", " :start_time = \"20150521T042008Z\" ;\n", " :stop_time = \"20150521T042506Z\" ;\n", " :time_coverage_duration = \"P1D\" ;\n", " :time_coverage_resolution = \"P1D\" ;\n", " :institution = \"ABOM\" ;\n", " :project = \"eReefs - Marine Water Quality\" ;\n", " :creator_name = \"National Plan for Environmental Information\" ;\n", " :creator_email = \"ereefs_support@bom.gov.au\" ;\n", " :creator_url = \"http://www.bom.gov.au/environment/\" ;\n", " :acknowledgment = \"Any use of these data requires the following acknowledgment: \\\"Marine water quality indices produced by the Australian Bureau of Meteorology as a contribution to eReefs - a collaboration between the Great Barrier Reef Foundation, Australian Government | Bureau of Meteorology, Commonwealth Scientific and Industrial Research Organisation, Australian Government | Australian Institute of Marine Science and the Queensland Government.\\\" Data are acquired from NASA spacecraft by the Bureau, Australian Institute of Marine Science, and the Commonwealth Scientific and Industrial Research Organization.\" ;\n", " :license = \"Copyright for any data supplied by the Bureau of Meteorology is held in the Commonwealth of Australia and the purchaser shall give acknowledgement of the source in reference to the data. Apart from dealings under the Copyright Act 1968, the purchaser shall not reproduce (electronically or otherwise), modify or supply (by sale or otherwise) these data without written permission from the supplier.\" ;\n", " :disclaimer = \"You accept all risks and responsibility for losses, damages, costs and other consequences resulting directly or indirectly from using Bureau of Meteorology data and any information or material available from it. To the maximum permitted by law, the Bureau of Meteorology excludes all liability to any person arising directly or indirectly from using this data and any information or material available from it. The data may not be accurate, current or complete\" ;\n", " :history = \"mwq_L3_processor using pyresample (EDR)\" ;\n", " :source = \"A2015141023000.SEADAS.hdf, A2015141023000.ANN.hdf, A2015141023000.ANN_MIM.hdf, A2015141023500.SEADAS.hdf, A2015141023500.ANN.hdf, A2015141023500.ANN_MIM.hdf, A2015141024000.SEADAS.hdf, A2015141024000.ANN.hdf, A2015141024000.ANN_MIM.hdf, A2015141040500.SEADAS.hdf, A2015141040500.ANN.hdf, A2015141040500.ANN_MIM.hdf, A2015141041000.SEADAS.hdf, A2015141041000.ANN.hdf, A2015141041000.ANN_MIM.hdf, A2015141041500.SEADAS.hdf, A2015141041500.ANN.hdf, A2015141041500.ANN_MIM.hdf, A2015141042000.SEADAS.hdf, A2015141042000.ANN.hdf, A2015141042000.ANN_MIM.hdf\" ;\n", " :uuid = \"def05096-0003-11e5-b7b0-001517d04ac5\" ;\n", " :date_created = \"20150521T215352Z\" ;\n", " }\n", "```" ] }, { "cell_type": "code", "execution_count": null, "id": "wrong-smooth", "metadata": {}, "outputs": [], "source": [] }, { "cell_type": "markdown", "id": "previous-apartment", "metadata": {}, "source": [ "## eReefs data catalogs\n", "\n", "\n", "There are many places where you could find eReefs dataset. Here is a non-exhaustive list of some of the servers we will be using during the course.\n", "\n", "\n", "\n", "### Hosted by the Australian Institute of Marine Science (AIMS)\n", "\n", "The [AIMS eReefs THREDDS server](http://thredds.ereefs.aims.gov.au/thredds/catalog.html) provides access via OPeNDAP for all NetCDF files produced by the AIMS eReefs system. The AIMS eReefs THREDDS service contains regridded and aggregated format of the eReefs model output.\n", "\n", "\n", ":::{figure-md} fig-target7\n", ":class: myclass\n", "\n", "\"timeseries\"\n", "\n", "Different time span and sample rate for eReefs dataset \n", ":::\n", "\n", "The hydrodynamics is modelled at 1 km and 4 km resolution and is available as hourly data. \n", "The biogeochemical model is available at 4 km resolution and has daily (midday sample) data available.\n", "\n", "**Hydrodynamic:**\n", "\n", "- 1km December 2014 - hourly\n", "- 4km September 2010 - hourly\n", "\n", "**Biogeochemical:**\n", "\n", "- 4km Jan 2015 - daily\n", "\n", "Following the following steps will help you find the OpenDAP URL of your dataset. Same approach will work with the 2 others servers described below (NCI and BOM).\n", "\n", "1. Open the [AIMS eReefs THREDDS server](http://thredds.ereefs.aims.gov.au/thredds/catalog.html) website and select the link Data derived from the eReefs model.\n", "2. On the next page select the link to the required model\n", " - [GBR4_H2p0_B3p1_Cq3P_Dhnd](http://thredds.ereefs.aims.gov.au/thredds/s3catalogue/aims-ereefs-public-prod/derived/ncaggregate/ereefs/GBR4_H2p0_B3p1_Cq3P_Dhnd/catalog.html): eReefs BioGeoChemical model version 3.1 (4 km resolution) - source catchments using Pre-Industrial catchment conditions\n", " - [GBR4_H2p0_B3p1_Cq3R_Dhnd](http://thredds.ereefs.aims.gov.au/thredds/s3catalogue/aims-ereefs-public-prod/derived/ncaggregate/ereefs/GBR4_H2p0_B3p1_Cq3R_Dhnd/catalog.html): eReefs BioGeoChemical model version 3.1 (4 km resolution) - source catchments using Hindcast catchment conditions (anthropogenic loads reduced according to the percentage reductions of DIN, PN, PP and TSS specified in the [Reef 2050 Water Quality Improvement Plan 2017-2022](https://www.reefplan.qld.gov.au/__data/assets/pdf_file/0017/46115/reef-2050-water-quality-improvement-plan-2017-22.pdf))\n", " - [GBR4_H2p0_B3p1_Cq3b_Dhnd](http://thredds.ereefs.aims.gov.au/thredds/s3catalogue/aims-ereefs-public-prod/derived/ncaggregate/ereefs/GBR4_H2p0_B3p1_Cq3b_Dhnd/catalog.html): eReefs BioGeoChemical model version 3.1 (4 km resolution) - source catchments using Baseline catchment conditions.\n", " - [gbr1_2.0](http://thredds.ereefs.aims.gov.au/thredds/s3catalogue/aims-ereefs-public-prod/derived/ncaggregate/ereefs/gbr1_2.0/catalog.html): eReefs Hydrodynamic model version 2.0 (1 km resolution)\n", " - [gbr4_v2](http://thredds.ereefs.aims.gov.au/thredds/s3catalogue/aims-ereefs-public-prod/derived/ncaggregate/ereefs/gbr4_v2/catalog.html): Reefs Hydrodynamic model version 2.0 (4 km resolution)\n", "3. Each model has its derived output grouped into folders with the names indicating the time steps and aggregation in a file. For example a folder with the name\"daily-monthly\" contains \"monthly\" files with \"daily\" data while a folder with the name \"annual-annual\" contains \"annual\" files with \"annual\" data. Select the link to the folder of interest.\n", "4. In the list of NetCDF files, select the one of interest. The file names describe the data they contain with the structure \"EREEFS_organisations_model_timestep-aggregation-date.nc\". For example the file \"EREEFS_AIMS-CSIRO_gbr4_v2_hydro_daily-monthly-2010-09.nc\" can be broken down into:\n", " - \"AIMS-CSIRO\" := Reference to the organisations AIMS and CSIRO\n", " - \"gbr4_v2_hydro\" := eReefs Hydrodynamic model version 2.0 (4 km resolution)\n", " - \"daily\" := \"daily\" data\n", " - \"monthly\" := one month of data\n", " - \"2010-09\" := data for September 2010\n", "5. On the single file page in the section \"Access\" click the link \"OPENDAP\"\n", "6. On the next page copy the value of the input field \"Data URL\". \n", "\n", "\n", "### Hosted on the National Computational Infrastructure (NCI)\n", "\n", "\n", "[**Summary table of the latest model simulations available on the eReefs visualization portal and NCI.**](https://research.csiro.au/ereefs/models/model-outputs/access-to-raw-model-output/)\n", "\n", "You can also visit the NCI catalog [**here**](http://dapds00.nci.org.au/thredds/catalogs/fx3/catalog.html).\n", "\n", "- [For long simulations with consistent forcing (up to 2018-10)](http://dapds00.nci.org.au/thredds/catalog/fx3/gbr4_bgc_GBR4_H2p0_B3p0_Chyd_Dcrt/catalog.html)\n", "- [For the most uptodate (and in 1 km)](http://dapds00.nci.org.au/thredds/catalog/fx3/gbr1_bgc_924/catalog.html)\n", "\n", "More information about the different models are available from this [link](https://regional-models.ereefs.info/thredds/catalog/catalog.html).\n", "\n", ":::{admonition} Biogeochemical simulation naming protocol:\n", ":class: tip\n", "\n", "All simulations from 2017 onwards have the following naming structure:\n", "\n", "**GBRg_Hhhh_Bbbb_Cccc_Dddd**\n", "\n", "where:\n", "\n", "- GBRg – Model grid with g = approximate grid resolution in kilometres.\n", "- Hhhh – Hydrodynamic model, hhh = model version.\n", "- Bbbb – Biogeochemical model, bbb = model version.\n", "- Cccc – Catchment model, ccc = load specification.\n", "\n", "For the full naming convention visit this [page](https://research.csiro.au/ereefs/models/models-about/biogeochemical-simulation-naming-protocol/).\n", ":::\n", "\n", "\n", "\n", "### Hosted by the Bureau of Meteorology\n", "\n", "The [ereeftds.bom.gov.au](http://ereeftds.bom.gov.au/ereefs/tds/catalogs/ereefs_data.html) is another place where additional dataset and derived products could be found such as:\n", "\n", "- Catchment modelling\n", "- Monitoring water quality program output\n", "- Reef temperature\n" ] }, { "cell_type": "code", "execution_count": null, "id": "latin-craps", "metadata": {}, "outputs": [], "source": [] } ], "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.8.8" } }, "nbformat": 4, "nbformat_minor": 5 }