Adding observation data#

This tutorial demonstrates how OpenGHG can be used to process new measurement data, search the data present and to retrieve this for analysis and visualisation.

What is an object store?#

Each object and piece of data in the object store is stored at a specific key, which can be thought of as the address of the data. The data is stored in a bucket which in the cloud is a section of the OpenGHG object store. Locally a bucket is just a normal directory in the user’s filesystem specified by the path given in the configuration file at ~/.config/openghg/openghg.conf.

0. Using the tutorial object store#

An object store is a folder with a fixed structure within which openghg can read and write data. To avoid adding the example data we use in this tutorial to your normal object store, we need to tell OpenGHG to use a separate sandboxed object store that we’ll call the tutorial store. To do this we use the use_tutorial_store function from openghg.tutorial. This sets the OPENGHG_TUT_STORE environment variable for this session and won’t affect your use of OpenGHG outside of this tutorial.

from openghg.tutorial import use_tutorial_store

use_tutorial_store()

1. Adding and standardising data#

Note

Outside of this tutorial, if you have write access to multiple object stores you will need to pass the name of the object store you wish to write to to the store argument of the standardise functions.

Source formats#

OpenGHG can process and store several source formats in the object store, including data from the AGAGE, DECC, NOAA, LondonGHG, BEAC2ON networks. The process of adding data to the object store is called standardisation.

To standardise a new data file, you must specify the source format and other keywords for the data. Which keywords need to be specified may be dependent on the source format itself as some details can be inferred from the data or may not be relevant. For the full list of accepted observation inputs and source formats, call the function summary_source_formats:

from openghg.standardise import summary_source_formats

summary = summary_source_formats()

## UNCOMMENT THIS CODE TO SHOW ALL ENTRIES
# import pandas as pd; pd.set_option('display.max_rows', None)

summary
Source format Site code Instrument Network Species file_format Long name Platform
0 CRDS RPB CRDS AGAGE NaN NaN Ragged Point, Barbados surface site
1 CRDS HFD CRDS DECC NaN NaN Heathfield, UK surface site
2 CRDS BSD CRDS DECC NaN NaN Bilsdale, UK surface site
3 CRDS TTA CRDS DECC NaN NaN Angus Tower, UK surface site
4 CRDS RGL CRDS DECC NaN NaN Ridge Hill, UK surface site
... ... ... ... ... ... ... ... ...
339 NOAA WSD NaN NaN NaN NaN Wessington, South Dakota surface site
340 NOAA YON NaN NaN NaN NaN Yonagunijima, Japan surface site
341 NOAA ZEP NaN NaN NaN NaN Zeppelin, Ny Alesund, Norway surface site
342 NPL NPL NaN LGHG NaN NaN National Physical Laboratory surface site
343 NIWA ARH NaN NaN NaN NaN Arrival Heights, New Zealand surface site

344 rows × 8 columns

There may be multiple source formats for a given site. For instance, the Tacolneston site in the UK (site code “TAC”) has four entries:

summary[summary["Site code"] == "TAC"]
Source format Site code Instrument Network Species file_format Long name Platform
5 CRDS TAC CRDS DECC NaN NaN Tacolneston Tower, UK surface site
32 GCWERKS TAC GCMD DECC NaN NaN Tacolneston Tower, UK surface site
34 GCWERKS TAC medusa DECC NaN NaN Tacolneston Tower, UK surface site
302 NOAA TAC NaN NaN NaN NaN Tacolneston Tower, UK surface site

Let’s see what data is available for a given source. First, we’ll list all source formats.

summary["Source format"].unique()

array(['CRDS', 'GCWERKS', 'AGAGE', 'ICOS', 'NOAA', 'NPL', 'NIWA'],
      dtype=object)

Now we’ll find all data with source format "CRDS".

summary[summary["Source format"] == "CRDS"]
Source format Site code Instrument Network Species file_format Long name Platform
0 CRDS RPB CRDS AGAGE NaN NaN Ragged Point, Barbados surface site
1 CRDS HFD CRDS DECC NaN NaN Heathfield, UK surface site
2 CRDS BSD CRDS DECC NaN NaN Bilsdale, UK surface site
3 CRDS TTA CRDS DECC NaN NaN Angus Tower, UK surface site
4 CRDS RGL CRDS DECC NaN NaN Ridge Hill, UK surface site
5 CRDS TAC CRDS DECC NaN NaN Tacolneston Tower, UK surface site

DECC network#

We will start by adding data to the object store from Tacolneston, which is a surface site in the DECC network. (Data at surface sites is measured in-situ.)

First we retrieve the raw data.

from openghg.tutorial import retrieve_example_data

data_url = "https://github.com/openghg/example_data/raw/main/timeseries/tac_example.tar.gz"

tac_data = retrieve_example_data(url=data_url)







Now we add this data to the object store using standardise_surface, passing the
following arguments:


    

  • filepath: list of paths to .dat files
    • 

  • site:  "TAC", the site code for Tacolneston
    • 

  • network: "DECC"
    • 

  • source_format: "CRDS", the type of data we want to process
    • 







from openghg.standardise import standardise_surface

decc_results = standardise_surface(filepath=tac_data, source_format="CRDS", site="TAC", network="DECC")

decc_results









[{'uuid': '2ba92692-1f8a-4db0-a9da-83b864f07682',
  'new': True,
  'site': 'tac',
  'instrument': 'picarro',
  'sampling_period': '3600.0',
  'inlet': '54m',
  'network': 'decc',
  'species': 'ch4',
  'source_format': 'CRDS',
  'data_source': 'internal',
  'file': 'tac.picarro.hourly.54m.dat'},
 {'uuid': '18b960d8-e000-480c-89e6-ab261a9e37bc',
  'new': True,
  'site': 'tac',
  'instrument': 'picarro',
  'sampling_period': '3600.0',
  'inlet': '54m',
  'network': 'decc',
  'species': 'co2',
  'source_format': 'CRDS',
  'data_source': 'internal',
  'file': 'tac.picarro.hourly.54m.dat'},
 {'uuid': '5f17a888-2375-4b6c-9d20-8576ac49b782',
  'new': True,
  'site': 'tac',
  'instrument': 'picarro',
  'sampling_period': '3600.0',
  'inlet': '100m',
  'network': 'decc',
  'species': 'ch4',
  'source_format': 'CRDS',
  'data_source': 'internal',
  'file': 'tac.picarro.hourly.100m.dat'},
 {'uuid': '1612d20d-ebb1-40fb-a614-ce525da9e425',
  'new': True,
  'site': 'tac',
  'instrument': 'picarro',
  'sampling_period': '3600.0',
  'inlet': '100m',
  'network': 'decc',
  'species': 'co2',
  'source_format': 'CRDS',
  'data_source': 'internal',
  'file': 'tac.picarro.hourly.100m.dat'},
 {'uuid': '49ea5094-07bf-476e-a9ae-f278e39c27d6',
  'new': True,
  'site': 'tac',
  'instrument': 'picarro',
  'sampling_period': '3600.0',
  'inlet': '185m',
  'network': 'decc',
  'species': 'ch4',
  'source_format': 'CRDS',
  'data_source': 'internal',
  'file': 'tac.picarro.hourly.185m.dat'},
 {'uuid': 'b31653ca-9643-4582-bdbf-99b904f151c1',
  'new': True,
  'site': 'tac',
  'instrument': 'picarro',
  'sampling_period': '3600.0',
  'inlet': '185m',
  'network': 'decc',
  'species': 'co2',
  'source_format': 'CRDS',
  'data_source': 'internal',
  'file': 'tac.picarro.hourly.185m.dat'}]









This extracts the data and metadata from the files,
standardises them, and adds them to our object store. The keywords of site and network,
along with details extracted from the data itself allow us to uniquely store the data.


The returned decc_results dictionary shows how the data
has been stored: each file has been split into several entries, each with a unique ID (UUID).
Each entry is known as a Datasource (see Note on Datasources).


The decc_results output includes details of the processed data and tells
us that the data has been stored correctly. This will also tell us if
any errors have been encountered when trying to access and standardise
this data.






AGAGE data#


OpenGHG can also process data from the AGAGE network.


Historically, the AGAGE network produces output files from GCWERKS alongside a seperate precisions file. If you wish
to use this form of input file, we create a tuple with the data filename and the precisions filename. For example:


First we retrieve example data from the  Cape Grim station in Australia (site code “CGO””).






cgo_url = "https://github.com/openghg/example_data/raw/main/timeseries/capegrim_example.tar.gz"

capegrim_data = retrieve_example_data(url=cgo_url)















capegrim_data is a list of two file paths, one for the data file and one for the precisions file:


[PosixPath('/Users/bm13805/openghg_store/tutorial_store/extracted_files/capegrim.18.C'),
PosixPath('/Users/bm13805/openghg_store/tutorial_store/extracted_files/capegrim.18.precisions.C')]





We put the data file and precisions file into a tuple:






capegrim_tuple = (capegrim_data[0], capegrim_data[1])













We can add these files to the object store in the same way as the DECC
data by including the right arguments:


    

  • filepath: tuple (or list of tuples) with paths to data and precision files
    • 

  • site (site code): "CGO"
    • 

  • network: "AGAGE"
    • 

  • instrument: "medusa"
    • 

  • source_format (data type): "GCWERKS"
    • 







agage_results = standardise_surface(filepath=capegrim_tuple, source_format="GCWERKS", site="CGO",
                              network="AGAGE", instrument="medusa")
agage_results









[{'uuid': 'e852d88f-a5b5-46b5-bd0d-e65a682d933a',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'ch4',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': 'ad0b5210-3ab3-4216-8fc3-3a294b18d15b',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'cfc12',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': 'efb0fdca-204b-4cb7-891c-791bfe95360c',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'n2o',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': 'c1b91285-356f-4d42-9d7f-f69f586cc340',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'cfc11',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': '06348c15-d464-4165-8399-1aeb49483e74',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'cfc113',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': '1f64cdd2-17d1-4a37-a625-9b890b5058fb',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'chcl3',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': '22436f09-1e81-441e-8ab0-35e3508f9bbd',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'ch3ccl3',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': '762f12e9-e7f7-4b42-a77e-87461fbad263',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'ccl4',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': '6a79ed7f-3dbb-44e7-9d9c-86416db1546b',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'h2',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': '28215145-ef7e-42a6-94fc-e0a1a1fc990c',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'co',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'},
 {'uuid': '5e0a7f13-e480-48e4-b7a5-d092090ed12e',
  'new': True,
  'instrument': 'medusa',
  'site': 'cgo',
  'network': 'agage',
  'sampling_period': '1200',
  'inlet': '70m',
  'species': 'ne',
  'source_format': 'GCWERKS',
  'data_source': 'internal',
  'file': 'capegrim.18.C'}]









When viewing agage_results there will be a large number of
Datasource UUIDs shown due to the large number of gases in each data
file


However, recently the AGAGE network has begun to also produce netCDF files, which are processed by Matt
Rigby’s agage-archive repository. These files are split by site,
species and instrument and do not need an accompanying precisions file. These can also be read in by the
openghg.standardise.standardise_surface function, with the arguments:


    

  • filepath: filepath to the .nc file
    • 

  • site (site code): "CGO"
    • 

  • source_format (data type): "AGAGE"
    • 

  • network: "AGAGE"
    • 

  • instrument: "medusa"
    • 



The data will be processed in the same way as the old AGAGE data, and stored in the object store accordingly.
Ensure that the source_format argument matches the input filetype, as the two are not compatible.




Note on Datasources#


Datasources are objects that are stored in the object store that hold the data and metadata associated with
each measurement we upload to the platform.


For example, if we upload a file that contains readings for three gas
species from a single site at a specific inlet height OpenGHG will
assign this data to three different Datasources, one for each species.
Metadata such as the site, inlet height, species, network etc are stored
alongside the measurements for easy searching.


Datasources can also handle multiple versions of data from a single
site, so if scales or other factors change multiple versions may be
stored for easy future comparison.








Other keywords#


When adding data in this way there are other keywords which can be used to
distinguish between different data sets as required including:


    

  • instrument: Name of the instrument
    • 

  • sampling_period: The time taken for each measurement to be sampled
    • 

  • data_level: The level of quality control which has been applied to the data.
    • 

  • data_sublevel:  Optional level to include between data levels. Typically for level 1 data where multiple steps of initial QA may have been applied.
    • 

  • dataset_source: Name of the dataset if data is taken from a larger source e.g. from an ObsPack
    • 



See the standardise_surface documentation for a full list of inputs.






Informational keywords#


In addition to the keywords demonstrated for adding data and described above which are used to distinguish
between different data sets being stored, the following informational details can also be added to help describe the data.




Using the tag keyword#


The tag keyword allows one or multiple short labels to be specified which can be the same across multiple
data sources. For instance, data from different sites which is associated with a particular project could all be
added using the same tag. For example below we show how to add the same data as above with a tag:


    

  • Tacolneston (TAC) data with a tag of “project1”
    • 

  • Cape Grim (CGO) data with a tag of both “project1” and “project2”
    • 







from openghg.standardise import standardise_surface

decc_results = standardise_surface(filepath=tac_data,
                                   source_format="CRDS",
                                   site="TAC",
                                   network="DECC",
                                   tag="project1",
                                   force=True)

agage_results = standardise_surface(filepath=capegrim_tuple,
                                    source_format="GCWERKS",
                                    site="CGO",
                                    network="AGAGE",
                                    instrument="medusa",
                                    tag=["project1", "project2"],
                                    force=True)













Note: here we included the force=True keyword as we are adding the same data which has been added in
a previous step of the tutorial - see “Updating existing data” tutorial for more details of this.


As will be covered in the 2. Searching for data section, these keywords can then used when searching the
object store. For the tag keyword this can be used to return all data which includes the chosen tag.






Adding informational keys#


Informational keys and associated values can also be added using the info_metadata input. The most
common example for this would be to add a comment input. For example:


decc_results = standardise_surface(filepath=tac_data,
                                   source_format="CRDS",
                                   site="TAC",
                                   network="DECC",
                                   info_metadata={"comment": "Automatic quality checks have been applied."})





Note that for both info_metadata and tag that these options are available for all data types (not just
observations).








Multiple stores#


If you have write access to more than one object store you’ll need to pass in the name of that store
to the store argument.
So instead of the standardise_surface call above, we’ll tell it to write to our default user object store. This is our default local object store
created when we run openghg --quickstart.


from openghg.standardise import standardise_surface

decc_results = standardise_surface(filepath=tac_data, source_format="CRDS", site="TAC", network="DECC", store="user")





The store argument can be passed to any of the standardise functions in OpenGHG and is required if you have write access
to more than one store.








2. Searching for data#




Searching the object store#


We can search the object store by property using the
search_surface(...) function. This function retrieves all of the metadata associated with the search query from the data in the object store.


For example we can find all sites which have measurements for carbon
tetrafluoride (“cf4”) using the species keyword:






from openghg.retrieve import search_surface

cfc_results = search_surface(species="cfc11")
cfc_results.results













  
    

      
      instrument
      site
      network
      sampling_period
      units
      calibration_scale
      inlet
      species
      data_type
      species_alt
      ...
      platform
      data_source
      uuid
      latest_version
      timestamp
      start_date
      end_date
      versions
      tag
      object_store
    

  
  
    

      0
      medusa
      cgo
      agage
      1200
      ppt
      sio-05
      70m
      cfc11
      surface
      cfc-11
      ...
      not_set
      internal
      c1b91285-356f-4d42-9d7f-f69f586cc340
      v2
      2025-07-15 15:38:25.387116+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
    

  



1 rows × 31 columns






We could also look for details of all the data measured at the Tacolneston
(“TAC”) site using the site keyword:






tac_results = search_surface(site="tac")
tac_results.results













  
    

      
      site
      instrument
      sampling_period
      inlet
      port
      type
      network
      species
      calibration_scale
      long_name
      ...
      platform
      data_source
      uuid
      latest_version
      timestamp
      start_date
      end_date
      versions
      tag
      object_store
    

  
  
    

      0
      tac
      picarro
      3600.0
      54m
      8
      air
      decc
      ch4
      wmo-x2004a
      tacolneston
      ...
      not_set
      internal
      2ba92692-1f8a-4db0-a9da-83b864f07682
      v2
      2025-07-15 15:38:24.219027+00:00
      2012-07-26 11:23:05+00:00
      2017-12-19 11:25:19+00:00
      {'v1': ['2012-07-26-11:23:05+00:00_2017-12-19-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

    

      1
      tac
      picarro
      3600.0
      54m
      8
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      not_set
      internal
      18b960d8-e000-480c-89e6-ab261a9e37bc
      v2
      2025-07-15 15:38:24.243145+00:00
      2012-07-26 11:23:05+00:00
      2017-12-19 11:25:19+00:00
      {'v1': ['2012-07-26-11:23:05+00:00_2017-12-19-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

    

      2
      tac
      picarro
      3600.0
      100m
      9
      air
      decc
      ch4
      wmo-x2004a
      tacolneston
      ...
      not_set
      internal
      5f17a888-2375-4b6c-9d20-8576ac49b782
      v2
      2025-07-15 15:38:24.623910+00:00
      2012-07-26 11:04:07+00:00
      2018-01-01 00:23:04+00:00
      {'v1': ['2012-07-26-11:04:07+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

    

      3
      tac
      picarro
      3600.0
      100m
      9
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      not_set
      internal
      1612d20d-ebb1-40fb-a614-ce525da9e425
      v2
      2025-07-15 15:38:24.647108+00:00
      2012-07-26 11:04:07+00:00
      2018-01-01 00:23:04+00:00
      {'v1': ['2012-07-26-11:04:07+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

    

      4
      tac
      picarro
      3600.0
      185m
      10
      air
      decc
      ch4
      wmo-x2004a
      tacolneston
      ...
      not_set
      internal
      49ea5094-07bf-476e-a9ae-f278e39c27d6
      v2
      2025-07-15 15:38:24.989235+00:00
      2013-01-31 00:13:28+00:00
      2018-01-01 00:53:06+00:00
      {'v1': ['2013-01-31-00:13:28+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

    

      5
      tac
      picarro
      3600.0
      185m
      10
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      not_set
      internal
      b31653ca-9643-4582-bdbf-99b904f151c1
      v2
      2025-07-15 15:38:25.010999+00:00
      2013-01-31 00:13:28+00:00
      2018-01-01 00:53:06+00:00
      {'v1': ['2013-01-31-00:13:28+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

  



6 rows × 32 columns






For this site you can see this contains details of each of the species
as well as the inlet heights these were measured at.






Searching by tag keyword#


We can also search by the tag keyword when this has been set. Even though the tag
keyword can contain multiple values, this will find all the datasources where the
tag value is included (rather than needing an exact match like the other keywords).


For the “TAC” and “CGO” data we added the “project1” tag and so this data can be found
using this keyword:






results = search_surface(tag="project1")
results.results













  
    

      
      site
      instrument
      sampling_period
      inlet
      port
      type
      network
      species
      calibration_scale
      long_name
      ...
      uuid
      latest_version
      timestamp
      start_date
      end_date
      versions
      tag
      object_store
      units
      species_alt
    

  
  
    

      0
      tac
      picarro
      3600.0
      54m
      8
      air
      decc
      ch4
      wmo-x2004a
      tacolneston
      ...
      2ba92692-1f8a-4db0-a9da-83b864f07682
      v2
      2025-07-15 15:38:24.219027+00:00
      2012-07-26 11:23:05+00:00
      2017-12-19 11:25:19+00:00
      {'v1': ['2012-07-26-11:23:05+00:00_2017-12-19-...
      [project1]
      /home/runner/openghg_store/tutorial_store
      NaN
      NaN
    

    

      1
      tac
      picarro
      3600.0
      54m
      8
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      18b960d8-e000-480c-89e6-ab261a9e37bc
      v2
      2025-07-15 15:38:24.243145+00:00
      2012-07-26 11:23:05+00:00
      2017-12-19 11:25:19+00:00
      {'v1': ['2012-07-26-11:23:05+00:00_2017-12-19-...
      [project1]
      /home/runner/openghg_store/tutorial_store
      NaN
      NaN
    

    

      2
      tac
      picarro
      3600.0
      100m
      9
      air
      decc
      ch4
      wmo-x2004a
      tacolneston
      ...
      5f17a888-2375-4b6c-9d20-8576ac49b782
      v2
      2025-07-15 15:38:24.623910+00:00
      2012-07-26 11:04:07+00:00
      2018-01-01 00:23:04+00:00
      {'v1': ['2012-07-26-11:04:07+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
      NaN
      NaN
    

    

      3
      tac
      picarro
      3600.0
      100m
      9
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      1612d20d-ebb1-40fb-a614-ce525da9e425
      v2
      2025-07-15 15:38:24.647108+00:00
      2012-07-26 11:04:07+00:00
      2018-01-01 00:23:04+00:00
      {'v1': ['2012-07-26-11:04:07+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
      NaN
      NaN
    

    

      4
      tac
      picarro
      3600.0
      185m
      10
      air
      decc
      ch4
      wmo-x2004a
      tacolneston
      ...
      49ea5094-07bf-476e-a9ae-f278e39c27d6
      v2
      2025-07-15 15:38:24.989235+00:00
      2013-01-31 00:13:28+00:00
      2018-01-01 00:53:06+00:00
      {'v1': ['2013-01-31-00:13:28+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
      NaN
      NaN
    

    

      5
      tac
      picarro
      3600.0
      185m
      10
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      b31653ca-9643-4582-bdbf-99b904f151c1
      v2
      2025-07-15 15:38:25.010999+00:00
      2013-01-31 00:13:28+00:00
      2018-01-01 00:53:06+00:00
      {'v1': ['2013-01-31-00:13:28+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
      NaN
      NaN
    

    

      6
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      ch4
      tu1987
      NaN
      ...
      e852d88f-a5b5-46b5-bd0d-e65a682d933a
      v2
      2025-07-15 15:38:25.348381+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppb
      NaN
    

    

      7
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      cfc12
      sio-05
      NaN
      ...
      ad0b5210-3ab3-4216-8fc3-3a294b18d15b
      v2
      2025-07-15 15:38:25.361383+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppt
      cfc-12
    

    

      8
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      n2o
      sio-16
      NaN
      ...
      efb0fdca-204b-4cb7-891c-791bfe95360c
      v2
      2025-07-15 15:38:25.374231+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppb
      NaN
    

    

      9
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      cfc11
      sio-05
      NaN
      ...
      c1b91285-356f-4d42-9d7f-f69f586cc340
      v2
      2025-07-15 15:38:25.387116+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppt
      cfc-11
    

    

      10
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      cfc113
      sio-05
      NaN
      ...
      06348c15-d464-4165-8399-1aeb49483e74
      v2
      2025-07-15 15:38:25.399980+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppt
      cfc-113
    

    

      11
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      chcl3
      sio-98
      NaN
      ...
      1f64cdd2-17d1-4a37-a625-9b890b5058fb
      v2
      2025-07-15 15:38:25.413001+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppt
      NaN
    

    

      12
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      ch3ccl3
      sio-05
      NaN
      ...
      22436f09-1e81-441e-8ab0-35e3508f9bbd
      v2
      2025-07-15 15:38:25.426400+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppt
      NaN
    

    

      13
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      ccl4
      sio-05
      NaN
      ...
      762f12e9-e7f7-4b42-a77e-87461fbad263
      v2
      2025-07-15 15:38:25.439173+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppt
      NaN
    

    

      14
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      h2
      mpi-2009
      NaN
      ...
      6a79ed7f-3dbb-44e7-9d9c-86416db1546b
      v2
      2025-07-15 15:38:25.452114+00:00
      2018-01-01 00:30:00+00:00
      2018-12-27 00:02:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-27-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppb
      h2_pdd
    

    

      15
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      co
      csiro-94
      NaN
      ...
      28215145-ef7e-42a6-94fc-e0a1a1fc990c
      v2
      2025-07-15 15:38:25.465566+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ppb
      NaN
    

    

      16
      cgo
      medusa
      1200
      70m
      NaN
      NaN
      agage
      ne
      na
      NaN
      ...
      5e0a7f13-e480-48e4-b7a5-d092090ed12e
      v2
      2025-07-15 15:38:25.478124+00:00
      2018-01-01 00:30:00+00:00
      2018-11-19 10:54:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-11-19-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      na
      ne_pdd
    

  



17 rows × 34 columns






For the “CGO” data we also included the “project2” tag and we can find this
data by searching for this:






results = search_surface(tag="project2")
results.results













  
    

      
      instrument
      site
      network
      sampling_period
      units
      calibration_scale
      inlet
      species
      data_type
      inlet_height_magl
      ...
      data_source
      uuid
      latest_version
      timestamp
      start_date
      end_date
      versions
      tag
      object_store
      species_alt
    

  
  
    

      0
      medusa
      cgo
      agage
      1200
      ppb
      tu1987
      70m
      ch4
      surface
      70
      ...
      internal
      e852d88f-a5b5-46b5-bd0d-e65a682d933a
      v2
      2025-07-15 15:38:25.348381+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      NaN
    

    

      1
      medusa
      cgo
      agage
      1200
      ppt
      sio-05
      70m
      cfc12
      surface
      70
      ...
      internal
      ad0b5210-3ab3-4216-8fc3-3a294b18d15b
      v2
      2025-07-15 15:38:25.361383+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      cfc-12
    

    

      2
      medusa
      cgo
      agage
      1200
      ppb
      sio-16
      70m
      n2o
      surface
      70
      ...
      internal
      efb0fdca-204b-4cb7-891c-791bfe95360c
      v2
      2025-07-15 15:38:25.374231+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      NaN
    

    

      3
      medusa
      cgo
      agage
      1200
      ppt
      sio-05
      70m
      cfc11
      surface
      70
      ...
      internal
      c1b91285-356f-4d42-9d7f-f69f586cc340
      v2
      2025-07-15 15:38:25.387116+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      cfc-11
    

    

      4
      medusa
      cgo
      agage
      1200
      ppt
      sio-05
      70m
      cfc113
      surface
      70
      ...
      internal
      06348c15-d464-4165-8399-1aeb49483e74
      v2
      2025-07-15 15:38:25.399980+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      cfc-113
    

    

      5
      medusa
      cgo
      agage
      1200
      ppt
      sio-98
      70m
      chcl3
      surface
      70
      ...
      internal
      1f64cdd2-17d1-4a37-a625-9b890b5058fb
      v2
      2025-07-15 15:38:25.413001+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      NaN
    

    

      6
      medusa
      cgo
      agage
      1200
      ppt
      sio-05
      70m
      ch3ccl3
      surface
      70
      ...
      internal
      22436f09-1e81-441e-8ab0-35e3508f9bbd
      v2
      2025-07-15 15:38:25.426400+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      NaN
    

    

      7
      medusa
      cgo
      agage
      1200
      ppt
      sio-05
      70m
      ccl4
      surface
      70
      ...
      internal
      762f12e9-e7f7-4b42-a77e-87461fbad263
      v2
      2025-07-15 15:38:25.439173+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      NaN
    

    

      8
      medusa
      cgo
      agage
      1200
      ppb
      mpi-2009
      70m
      h2
      surface
      70
      ...
      internal
      6a79ed7f-3dbb-44e7-9d9c-86416db1546b
      v2
      2025-07-15 15:38:25.452114+00:00
      2018-01-01 00:30:00+00:00
      2018-12-27 00:02:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-27-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      h2_pdd
    

    

      9
      medusa
      cgo
      agage
      1200
      ppb
      csiro-94
      70m
      co
      surface
      70
      ...
      internal
      28215145-ef7e-42a6-94fc-e0a1a1fc990c
      v2
      2025-07-15 15:38:25.465566+00:00
      2018-01-01 00:30:00+00:00
      2018-12-31 23:24:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-12-31-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      NaN
    

    

      10
      medusa
      cgo
      agage
      1200
      na
      na
      70m
      ne
      surface
      70
      ...
      internal
      5e0a7f13-e480-48e4-b7a5-d092090ed12e
      v2
      2025-07-15 15:38:25.478124+00:00
      2018-01-01 00:30:00+00:00
      2018-11-19 10:54:59+00:00
      {'v1': ['2018-01-01-00:30:00+00:00_2018-11-19-...
      [project1, project2]
      /home/runner/openghg_store/tutorial_store
      ne_pdd
    

  



11 rows × 31 columns










Quickly retrieve data#


Say we want to retrieve all the co2 data from Tacolneston, we can
perform perform a search and expect a SearchResults
object to be returned. If no results are found None is returned.






results = search_surface(site="tac", species="co2")
results.results













  
    

      
      site
      instrument
      sampling_period
      inlet
      port
      type
      network
      species
      calibration_scale
      long_name
      ...
      platform
      data_source
      uuid
      latest_version
      timestamp
      start_date
      end_date
      versions
      tag
      object_store
    

  
  
    

      0
      tac
      picarro
      3600.0
      54m
      8
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      not_set
      internal
      18b960d8-e000-480c-89e6-ab261a9e37bc
      v2
      2025-07-15 15:38:24.243145+00:00
      2012-07-26 11:23:05+00:00
      2017-12-19 11:25:19+00:00
      {'v1': ['2012-07-26-11:23:05+00:00_2017-12-19-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

    

      1
      tac
      picarro
      3600.0
      100m
      9
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      not_set
      internal
      1612d20d-ebb1-40fb-a614-ce525da9e425
      v2
      2025-07-15 15:38:24.647108+00:00
      2012-07-26 11:04:07+00:00
      2018-01-01 00:23:04+00:00
      {'v1': ['2012-07-26-11:04:07+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

    

      2
      tac
      picarro
      3600.0
      185m
      10
      air
      decc
      co2
      wmo-x2019
      tacolneston
      ...
      not_set
      internal
      b31653ca-9643-4582-bdbf-99b904f151c1
      v2
      2025-07-15 15:38:25.010999+00:00
      2013-01-31 00:13:28+00:00
      2018-01-01 00:53:06+00:00
      {'v1': ['2013-01-31-00:13:28+00:00_2018-01-01-...
      [project1]
      /home/runner/openghg_store/tutorial_store
    

  



3 rows × 32 columns






We can retrieve either some or all of the data easily using the
retrieve function.






inlet_54m_data = results.retrieve(inlet="54m")
inlet_54m_data









<openghg.dataobjects._obsdata.ObsData at 0x7fc2ab4654c0>









Or we can retrieve all of the data and get a list of ObsData
objects.






all_co2_data = results.retrieve_all()
all_co2_data









[<openghg.dataobjects._obsdata.ObsData at 0x7fc2a8817c50>,
 <openghg.dataobjects._obsdata.ObsData at 0x7fc2aa28a300>,
 <openghg.dataobjects._obsdata.ObsData at 0x7fc2a8831340>]















3. Retrieving data#


To retrieve the standardised data from the object store there are
several functions we can use which depend on the type of data we want to
access.


To access the surface data we have added so far we can use the
get_obs_surface function and pass keywords for the site code,
species and inlet height to retrieve our data. Using get_* functions will only allow one set of data to be returned and will give details if this is not the case.


In this case we want to extract the carbon dioxide (“co2”) data from the
Tacolneston data (“TAC”) site measured at the “185m” inlet:






from openghg.retrieve import get_obs_surface

co2_data = get_obs_surface(site="tac", species="co2", inlet="185m")













If we view our returned obs_data variable this will contain:


    

  • data - The standardised data (accessed using
e.g. obs_data.data). This is returned as an xarray
Dataset.
    • 

  • metadata - The associated metadata (accessed using
e.g. obs_data.metadata).
    • 







co2_data









<openghg.dataobjects._obsdata.ObsData at 0x7fc2a88b78c0>













co2_data.data

























<xarray.Dataset> Size: 1MB
Dimensions:                    (time: 39114)
Coordinates:
  * time                       (time) datetime64[ns] 313kB 2013-01-31T00:13:2...
Data variables:
    mf                         (time) float64 313kB dask.array<chunksize=(19557,), meta=np.ndarray>
    mf_number_of_observations  (time) float64 313kB dask.array<chunksize=(19557,), meta=np.ndarray>
    mf_variability             (time) float64 313kB dask.array<chunksize=(19557,), meta=np.ndarray>
Attributes: (12/28)
    Conventions:           CF-1.8
    comment:               Cavity ring-down measurements. Output from GCWerks
    conditions_of_use:     Ensure that you contact the data owner at the outs...
    data_owner:            Simon O'Doherty
    data_owner_email:      s.odoherty@bristol.ac.uk
    data_source:           internal
    ...                    ...
    station_latitude:      52.51882
    station_long_name:     Tacolneston Tower, UK
    station_longitude:     1.1387
    tag:                   project1
    type:                  air
    scale:                 WMO-X2019








co2_data.metadata









{'data_type': 'surface',
 'site': 'tac',
 'instrument': 'picarro',
 'sampling_period': '3600.0',
 'inlet': '185m',
 'port': '10',
 'type': 'air',
 'network': 'decc',
 'species': 'co2',
 'calibration_scale': 'WMO-X2019',
 'long_name': 'tacolneston',
 'inlet_height_magl': '185',
 'data_owner': "Simon O'Doherty",
 'data_owner_email': 's.odoherty@bristol.ac.uk',
 'station_longitude': '1.1387',
 'station_latitude': '52.51882',
 'station_long_name': 'Tacolneston Tower, UK',
 'station_height_masl': 64,
 'source_format': 'CRDS',
 'data_level': 'not_set',
 'data_sublevel': 'not_set',
 'dataset_source': 'not_set',
 'platform': 'not_set',
 'data_source': 'internal',
 'uuid': 'b31653ca-9643-4582-bdbf-99b904f151c1',
 'latest_version': 'v2',
 'timestamp': '2025-07-15 15:38:25.010999+00:00',
 'start_date': '2013-01-31 00:13:28+00:00',
 'end_date': '2018-01-01 00:53:06+00:00',
 'versions': {'v1': ['2013-01-31-00:13:28+00:00_2018-01-01-00:53:06+00:00'],
  'v2': ['2013-01-31-00:13:28+00:00_2018-01-01-00:53:06+00:00']},
 'tag': 'project1',
 'object_store': '/home/runner/openghg_store/tutorial_store',
 'Conventions': 'CF-1.8',
 'comment': 'Cavity ring-down measurements. Output from GCWerks',
 'conditions_of_use': 'Ensure that you contact the data owner at the outset of your project.',
 'file_created': '2025-07-15 15:38:24.963920+00:00',
 'processed_by': 'OpenGHG_Cloud',
 'sampling_period_unit': 's',
 'source': 'In situ measurements of air',
 'scale': 'WMO-X2019'}









We can now make a simple plot using the plot_timeseries method of
the ObsData object.




NOTE: the plot created below may not show up on the online
documentation version of this notebook.








co2_data.plot_timeseries()

















You can also pass any of title, xlabel, ylabel and units
to the plot_timeseries function to modify the labels.






4. Cleanup#


If you’re finished with the data in this tutorial you can cleanup the
tutorial object store using the clear_tutorial_store function.






from openghg.tutorial import clear_tutorial_store

















clear_tutorial_store()