To improve argopy data fetching performances (in terms of time of retrieval), 2 solutions are available:

  • Cache fetched data, i.e. save your request locally so that you don’t have to fetch it again,

  • Use Parallel data fetching, i.e. fetch chunks of independent data simultaneously.

These solutions are explained below.

Note that another solution from standard big data strategies would be to fetch data lazily. But since (i) argopy post-processes raw Argo data on the client side and (ii) none of the data sources are cloud/lazy compatible, this solution is not possible (yet).

Let’s start with standard import:

In [1]: import argopy

In [2]: from argopy import DataFetcher


Caching data#

If you want to avoid retrieving the same data several times during a working session, or if you fetched a large amount of data, you may want to temporarily save data in a cache file.

You can cache fetched data with the fetchers option cache.

Argopy cached data are persistent, meaning that they are stored locally on files and will survive execution of your script with a new session. Cached data have an expiration time of one day, since this is the update frequency of most data sources. This will ensure you always have the last version of Argo data.

All data and meta-data (index) fetchers have a caching system.

The argopy default cache folder is under your home directory at ~/.cache/argopy.

But you can specify the path you want to use in several ways:

  • with argopy global options:

  • in a temporary context:

with argopy.set_options(cachedir='mycache_folder'):
    f = DataFetcher(cache=True)
  • when instantiating the data fetcher:

f = DataFetcher(cache=True, cachedir='mycache_folder')


You really need to set the cache option to True. Specifying only the cachedir won’t trigger caching !

Clearing the cache#

If you want to manually clear your cache folder, and/or make sure your data are newly fetched, you can do it at the fetcher level with the clear_cache method.

Start to fetch data and store them in cache:

In [3]: argopy.set_options(cachedir='mycache_folder')
Out[3]: <argopy.options.set_options at 0x7f642036a0d0>

In [4]: fetcher1 = DataFetcher(cache=True).profile(6902746, 34).load()

Fetched data are in the local cache folder:

In [5]: import os

In [6]: os.listdir('mycache_folder')
Out[6]: ['3d6aa407feabc6128d30f54845ff1d78012f0e05a5e791bcf7ed21dedd551a2c', 'cache']

where we see hash entries for the newly fetched data and the cache registry file cache.

We can then fetch something else using the same cache folder:

In [7]: fetcher2 = DataFetcher(cache=True).profile(1901393, 1).load()

All fetched data are cached:

In [8]: os.listdir('mycache_folder')

Note the new hash file from fetcher2 data.

It is important to note that we can safely clear the cache from the first fetcher1 data without removing fetcher2 data:

In [9]: fetcher1.clear_cache()
AttributeError                            Traceback (most recent call last)
Cell In[9], line 1
----> 1 fetcher1.clear_cache()

File ~/checkouts/, in ArgoDataFetcher.clear_cache(self)
    650 if not self.fetcher:
    651     raise InvalidFetcher(
    652         " Initialize an access point (%s) first."
    653         % ",".join(self.Fetchers.keys())
    654     )
--> 655 return self.fetcher.clear_cache()

File ~/checkouts/, in ArgoDataFetcherProto.clear_cache(self)
     45 def clear_cache(self):
     46     """ Remove cache files and entries from resources opened with this fetcher """
---> 47     return self.fs.clear_cache()

File ~/checkouts/, in argo_store_proto.clear_cache(self)
    269 if self.cache:
    270     for uri in self.cache_registry:
    271         # log.debug("Removing from cache %s" % uri)
--> 272         self._clear_cache_item(uri)
    273     self.cache_registry.clear()  # Reset registry

File ~/checkouts/, in argo_store_proto._clear_cache_item(self, uri)
    246 fn = os.path.join([-1], "cache")
    247 self.fs.load_cache()  # Read set of stored blocks from file and populate self.fs.cached_files
--> 248 cache = self.fs.cached_files[-1]
    249 if os.path.exists(fn):
    250     with open(fn, "rb") as f:

File ~/checkouts/, in CachingFileSystem.__getattribute__(self, item)
    413 # attributed belonging to the target filesystem
    414 cls = type(fs)
--> 415 m = getattr(cls, item)
    416 if (inspect.isfunction(m) or inspect.isdatadescriptor(m)) and (
    417     not hasattr(m, "__self__") or m.__self__ is None
    418 ):
    419     # instance method
    420     return m.__get__(fs, cls)

AttributeError: type object 'HTTPFileSystem' has no attribute 'cached_files'

In [10]: os.listdir('mycache_folder')

By using the fetcher level clear cache, you make sure that only data fetched with it are removed, while other fetched data (with other fetchers for instance) will stay in place.

If you want to clear the entire cache folder, whatever the fetcher used, do it at the package level with:

In [11]: argopy.clear_cache()

In [12]: os.listdir('mycache_folder')
Out[12]: []

Parallel data fetching#

Sometimes you may find that your request takes a long time to fetch, or simply does not even succeed. This is probably because you’re trying to fetch a large amount of data.

In this case, you can try to let argopy chunks your request into smaller pieces and have them fetched in parallel for you. This is done with the argument parallel of the data fetcher and can be tuned using options chunks and chunksize.

This goes by default like this:

# Define a box to load (large enough to trigger chunking):
In [13]: box = [-60, -30, 40.0, 60.0, 0.0, 100.0, "2007-01-01", "2007-04-01"]

# Instantiate a parallel fetcher:
In [14]: loader_par = DataFetcher(src='erddap', parallel=True).region(box)

you can also use the option progress to display a progress bar during fetching:

In [15]: loader_par = DataFetcher(src='erddap', parallel=True, progress=True).region(box)

In [16]: loader_par
Name: Ifremer erddap Argo data fetcher for a space/time region
Domain: [x=-60.00/-30.00; y=40.00/60.0 ... 00.0; t=2007-01-01/2007-04-01]
Performances: cache=False, parallel=True
User mode: standard
Dataset: phy

Then, you can fetch data as usual:

In [17]: %%time
   ....: ds = loader_par.to_xarray()
Final post-processing of the merged dataset () ...
CPU times: user 806 ms, sys: 24.1 ms, total: 830 ms
Wall time: 1.49 s

Number of chunks#

To see how many chunks your request has been split into, you can look at the uri property of the fetcher, it gives you the list of paths toward data:

In [18]: for uri in loader_par.uri:
   ....:     print("http: ... ", "&".join(uri.split("&")[1:-2]))  # Display only the relevant part of each URLs of URI:
http: ...  longitude>=-60.0&longitude<=-45.0&latitude>=40.0&latitude<=60.0&pres>=0.0&pres<=100.0&time>=1167609600.0&time<=1175385600.0
http: ...  longitude>=-45.0&longitude<=-30.0&latitude>=40.0&latitude<=60.0&pres>=0.0&pres<=100.0&time>=1167609600.0&time<=1175385600.0

To control chunking, you can use the ``chunks`` option that specifies the number of chunks in each of the direction:

  • lon, lat, dpt and time for a region fetching,

  • wmo for a float and profile fetching.

# Create a large box:
In [19]: box = [-60, 0, 0.0, 60.0, 0.0, 500.0, "2007", "2010"]

# Init a parallel fetcher:
In [20]: loader_par = DataFetcher(src='erddap',
   ....:                              parallel=True,
   ....:                              chunks={'lon': 5}).region(box)

# Check number of chunks:
In [21]: len(loader_par.uri)
Out[21]: 195

This creates 195 chunks, and 5 along the longitudinale direction, as requested.

When the chunks option is not specified for a given direction, it relies on auto-chunking using pre-defined chunk maximum sizes (see below). In the case above, auto-chunking appends also along latitude, depth and time; this explains why we have 195 and not only 5 chunks.

To chunk the request along a single direction, set explicitly all the other directions to 1:

# Init a parallel fetcher:
In [22]: loader_par = DataFetcher(src='erddap',
   ....:                              parallel=True,
   ....:                              chunks={'lon': 5, 'lat':1, 'dpt':1, 'time':1}).region(box)

# Check number of chunks:
In [23]: len(loader_par.uri)
Out[23]: 5

We now have 5 chunks along longitude, check out the URLs parameter in the list of URIs:

In [24]: for uri in loader_par.uri:
   ....:     print("&".join(uri.split("&")[1:-2])) # Display only the relevant URL part


You may notice that if you run the last command with the argovis fetcher, you will still have more than 5 chunks (i.e. 65). This is because argovis is limited to 3 months length requests. So, for this request that is 3 years long, argopy ends up with 13 chunks along time, times 5 chunks in longitude, leading to 65 chunks in total.


The gdac fetcher and the float and profile access points of the argovis fetcher use a list of resources than are not chunked but fetched in parallel using a batch queue.

Size of chunks#

The default chunk size for each access point dimensions are:

Access point dimension

Maximum chunk size

region / lon

20 deg

region / lat

20 deg

region / dpt

500 m or db

region / time

90 days

float / wmo


profile / wmo


These default values are used to chunk data when the chunks parameter key is set to auto.

But you can modify the maximum chunk size allowed in each of the possible directions. This is done with the option ``chunks_maxsize``.

For instance if you want to make sure that your chunks are not larger then 100 meters (db) in depth (pressure), you can use:

# Create a large box:
In [25]: box = [-60, -10, 40.0, 60.0, 0.0, 500.0, "2007", "2010"]

# Init a parallel fetcher:
In [26]: loader_par = DataFetcher(src='erddap',
   ....:                              parallel=True,
   ....:                              chunks_maxsize={'dpt': 100}).region(box)

# Check number of chunks:
In [27]: len(loader_par.uri)
Out[27]: 195

Since this creates a large number of chunks, let’s do this again and combine with the option chunks to see easily what’s going on:

# Init a parallel fetcher with chunking along the vertical axis alone:
In [28]: loader_par = DataFetcher(src='erddap',
   ....:                              parallel=True,
   ....:                              chunks_maxsize={'dpt': 100},
   ....:                              chunks={'lon':1, 'lat':1, 'dpt':'auto', 'time':1}).region(box)

In [29]: for uri in loader_par.uri:
   ....:     print("http: ... ", "&".join(uri.split("&")[1:-2])) # Display only the relevant URL part
http: ...  longitude>=-60&longitude<=-10&latitude>=40.0&latitude<=60.0&pres>=0.0&pres<=100.0&time>=1167609600.0&time<=1262304000.0
http: ...  longitude>=-60&longitude<=-10&latitude>=40.0&latitude<=60.0&pres>=100.0&pres<=200.0&time>=1167609600.0&time<=1262304000.0
http: ...  longitude>=-60&longitude<=-10&latitude>=40.0&latitude<=60.0&pres>=200.0&pres<=300.0&time>=1167609600.0&time<=1262304000.0
http: ...  longitude>=-60&longitude<=-10&latitude>=40.0&latitude<=60.0&pres>=300.0&pres<=400.0&time>=1167609600.0&time<=1262304000.0
http: ...  longitude>=-60&longitude<=-10&latitude>=40.0&latitude<=60.0&pres>=400.0&pres<=500.0&time>=1167609600.0&time<=1262304000.0

You can see, that the pres argument of this erddap list of URLs define layers not thicker than the requested 100db.

With the profile and float access points, you can use the wmo keyword to control the number of WMOs in each chunks.

In [30]: WMO_list = [6902766, 6902772, 6902914, 6902746, 6902916, 6902915, 6902757, 6902771]

# Init a parallel fetcher with chunking along the list of WMOs:
In [31]: loader_par = DataFetcher(src='erddap',
   ....:                              parallel=True,
   ....:                              chunks_maxsize={'wmo': 3}).float(WMO_list)

In [32]: for uri in loader_par.uri:
   ....:     print("http: ... ", "&".join(uri.split("&")[1:-2])) # Display only the relevant URL part
http: ...  platform_number=~"6902766|6902772|6902914"
http: ...  platform_number=~"6902746|6902916|6902915"
http: ...  platform_number=~"6902757|6902771"

You see here, that this request for 8 floats is split in chunks with no more that 3 floats each.


At this point, there is no mechanism to chunk requests along cycle numbers for the profile access point.

Parallelization methods#

They are 2 methods available to set-up your data fetching requests in parallel:

  1. Multi-threading for all data sources,

  2. Multi-processing for gdac with a local host.

Both options use a pool of threads or processes managed with the concurrent futures module.

The parallelization method is set with the parallel_method option of the fetcher, which can take as values thread or process.

Methods available for data sources:

Parallel method










Note that you can in fact pass the method directly with the parallel option, so that in practice, the following two formulations are equivalent:

In [33]: DataFetcher(parallel=True, parallel_method='thread')
<datafetcher.erddap> 'No access point initialised'
Available access points: float, profile, region
Performances: cache=False, parallel=True
User mode: standard
Dataset: phy

In [34]: DataFetcher(parallel='thread')
<datafetcher.erddap> 'No access point initialised'
Available access points: float, profile, region
Performances: cache=False, parallel=thread
User mode: standard
Dataset: phy

Comparison of performances#

Note that to compare performances with or without the parallel option, we need to make sure that data are not cached on the server side. To do this, we use a very small random perturbation on the box definition, here on the maximum latitude. This ensures that nearly the same amount of data will be requested but not cached by the server.

In [35]: def this_box():
   ....:     return [-60, 0,
   ....:            20.0, 60.0 + np.random.randint(0,100,1)[0]/1000,
   ....:            0.0, 500.0,
   ....:            "2007", "2009"]
In [36]: %%time
   ....: b1 = this_box()
   ....: f1 = DataFetcher(src='argovis', parallel=False).region(b1)
   ....: ds1 = f1.to_xarray()
CPU times: user 8.19 s, sys: 270 ms, total: 8.46 s
Wall time: 13.1 s
In [37]: %%time
   ....: b2 = this_box()
   ....: f2 = DataFetcher(src='argovis', parallel=True).region(b2)
   ....: ds2 = f2.to_xarray()
CPU times: user 8.43 s, sys: 310 ms, total: 8.73 s
Wall time: 9.88 s

This simple comparison hopefully shows that parallel request is significantly faster than the standard one.


  • Parallelizing your fetcher is useful to handle large region of data, but it can also add a significant overhead on reasonable size requests that may lead to degraded performances. So, we do not recommend for you to use the parallel option systematically.

  • You may have different dataset sizes with and without the parallel option. This may happen if one of the chunk data fetching fails. By default, data fetching of multiple resources fails with a warning. You can change this behaviour with the option errors of the to_xarray() fetcher methods, just set it to raise like this:


You can also use silent to simply hide all messages during fetching.