{"id":19310141,"url":"https://github.com/cedadev/kerchunk-tools","last_synced_at":"2025-09-11T17:49:16.753Z","repository":{"id":63712691,"uuid":"563853678","full_name":"cedadev/kerchunk-tools","owner":"cedadev","description":"Tools to work with kerchunk","archived":false,"fork":false,"pushed_at":"2023-08-30T14:58:01.000Z","size":722,"stargazers_count":3,"open_issues_count":15,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-24T03:27:56.506Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cedadev.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.rst","contributing":"CONTRIBUTING.rst","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":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-09T13:31:50.000Z","updated_at":"2024-04-24T20:11:38.000Z","dependencies_parsed_at":"2024-11-10T00:23:53.514Z","dependency_job_id":"190b097f-d780-42cf-a322-ce26feead14e","html_url":"https://github.com/cedadev/kerchunk-tools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cedadev/kerchunk-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fkerchunk-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fkerchunk-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fkerchunk-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fkerchunk-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cedadev","download_url":"https://codeload.github.com/cedadev/kerchunk-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cedadev%2Fkerchunk-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274681534,"owners_count":25330237,"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","status":"online","status_checked_at":"2025-09-11T02:00:13.660Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-10T00:22:46.644Z","updated_at":"2025-09-11T17:49:16.722Z","avatar_url":"https://github.com/cedadev.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kerchunk-tools\n\n## Overview\n\nThis is a set of tools for working with the \"kerchunk\" library:\n\n https://fsspec.github.io/kerchunk/\n\nKerchunk provides cloud-friendly indexing of data files without needing to move\nthe data itself.\n\nThe tools included here allow:\n - indexing of existing NetCDF files to kerchunk files\n - aggregation of existing NetCDF files to a single kerchunk file\n - tools to write to either POSIX file systems or S3-compatible object-store\n - a wrapper around `xarray` to ensure that the data can be read by Python\n - integration with access control to limit read/write operations as desired\n\nAn example notebook can be run using binder:\n\nhttps://mybinder.org/v2/gh/cedadev/kerchunk-tools.git/main?filepath=notebooks\n\n## Installation\n\n### Method 1: Install with miniconda\n\nFrom scratch, you can conda install with:\n\n```bash\nwget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh\nbash Miniconda3-latest-Linux-x86_64.sh -p ~/miniconda -b\n\nsource ~/miniconda/bin/activate\nconda create --name kerchunk-tools --file spec-file.txt\n\nconda activate kerchunk-tools\npip install -e . --no-deps\n```\n\n### Method 2: Install with Pip\n\nAssuming you have Python 3 installed, you can also install with Pip:\n\n```bash\npython -m venv venv\nsource venv/bin/activate\npip install --upgrade pip\npip install -r requirements.txt\npip install -e . --no-deps \n```\n\nNOTE: this installation method generated a lot of HDF5 library warnings \n      when reading data, which were not seen with the Conda install.\n\n## Basic usage\n\nHere is an example of using `kerchunk_tools` with authentication to the \nS3 service:\n\n```python\nimport kerchunk_tools.xarray_wrapper as wrap_xr\n\ns3_config = {\n    \"token\": \"TOKEN\",\n    \"secret\": \"SECRET\",\n    \"endpoint_url\": \"ENDPOINT_URL\"\n}\n\n# Load a Kerchunk file\n\n# Load a Kerchunk file\nindex_uri = \"s3://kc-indexes-cci-cloud-v2/BICEP-OC-L3S-PP-MERGED-1M_MONTHLY_9km_mapped-1998-2020-fv4.2.zstd\"\nds = wrap_xr.wrap_xr_open(index_uri, s3_config=s3_config)\n\n# Look at the metadata\nprint(ds)\npp = ds.pp\n\nprint(pp.shape, pp.dims)\n\n# Look at the data\nmx = ds.pp.sel(time=slice(\"1998-03-01\", \"2000-02-01\"), lat=slice(34, 40), lon=slice(20, 23)).max()\nmx = float(mx)\nprint(mx)\n\nassert 2137 \u003c mx \u003c 2139\n```\n\n## Testing\n\nIf you are connecting to a secured endpoint, then you will need three items for your S3 configuration:\n - `S3_TOKEN`\n - `S3_SECRET`\n - `S3_ENDPOINT_URL`\n\nThen you can run a full workflow that:\n - creates a bucket in S3\n - uploads some NetCDF files to S3\n - creates a kerchunk file in S3 (for a single NetCDF file)\n - creates a kerchunk file in S3 (for an aggregation of multiple NetCDF files)\n - read from the kerchunk files and extract/process a subset of data\n\n```\nS3_TOKEN=s3_token S3_SECRET=s3_secret S3_ENDPOINT_URL=s3_endpoint pytest tests/test_workflows/test_workflow_s3_quobyte_single.py -v\n```\n\n## Performance testing\n\nOur initial tests, having only run once, came out as follows:\n\nTable of test timings (in seconds). Where multiple values appear, the test was run multiple times.\n\n\n| Test type           | Read/process small subset | Read/process larger subset |\n|---------------------|---------------------------|----------------------------|\n| POSIX Kerchunk      |                  1.0, 0.7 |                 15.2, 37.9 |\n| S3-Quobyte Kerchunk |             1.1, 4.7, 1.3 |            8.5,  9.1,  5.7 |\n| S3-DataCore Zarr    |                  3.9, 3.8 |                 99.8, 99.2 |\n| POSIX Xarray        |                  0.6, 0.9 |                 86.0, 91.4 |\n\nWe need to run these repeatedly to validate them.\n\n### Test types\n\nThe test types are:\n1. POSIX Kerchunk:\n  - This uses a Kerchunk index file on the POSIX file system\n  - It references NetCDF files on the POSIX file system\n  - There is no use of object-store\n  - This test depends on having pre-generated the Kerchunk index file\n2. S3-Quobyte Kerchunk:\n  - This uses a Kerchunk index file in the JASMIN S3-Quobyte object-store\n  - It references NetCDF files in the S3-Quobyte object-store \n    - The files are actually part of the CEDA Archive and are exposed via an S3 interface\n  - There is no use of the POSIX file systems\n  - This test depends on having pre-generated the Kerchunk index file\n3. S3-DataCore Zarr:\n  - This reads a Zarr file that we have copied into the JASMIN DataCore (formerly Caringo) object-store\n  - The data is the same content as used for the other tests, converted from NetCDF to Zarr\n  - There is no use of Kerchunk\n  - This test depends on having pre-generated the Zarr file from NetCDF\n4. POSIX Xarray:\n  - This reads all the NetCDF files directly into Xarray (as a list of files)\n  - The files are read directly from the POSIX file system \n  - There is no pre-generation step for this test\n  - This is slower because the aggregation of the NetCDF content is done on-the-fly\n\n### Test data\n\nThe test data, being used is a list of 279 data files from the CCI archive, under the directory:\n\n```\n/neodc/esacci/ocean_colour/data/v5.0-release/geographic/netcdf/chlor_a/monthly/v5.0/\n```\n\nThe first and last files are:\n\n```\nFirst: .../1997/ESACCI-OC-L3S-CHLOR_A-MERGED-1M_MONTHLY_4km_GEO_PML_OCx-199709-fv5.0.nc \nLast:  .../2020/ESACCI-OC-L3S-CHLOR_A-MERGED-1M_MONTHLY_4km_GEO_PML_OCx-202011-fv5.0.nc \n```\n\n### Test details\n\nIn all cases the test is run as follows.\n\nTest 1 - Read/process small subset:\n\n1. Load the data as an `xarray.Dataset` object.\n2. Create a small time/lat/lon slice of shape: `(2, 144, 72)` (only 2 time steps == 2 files)\n3. Calculate the maximum value and assert it equals the expected value.     s = time.time()\n\nTest 2 - Read/process larger subset:\n\n1. Load the data as an `xarray.Dataset` object.\n2. Create a larger time/lat/lon slice of shape: `(279, 12, 24)` (279 time steps == 279 files)\n3. Calculate the maximum value and assert it equals the expected value. \n\n\n## Background reading and resources\n\nThese resources may be useful for understanding why we wanted to look at Kerchunk and how it fits into our bigger picture plans at CEDA:\n\nJASMIN Notebook service intro: https://www.youtube.com/watch?v=nle9teGLAb0\u0026list=PLhF74YhqhjqmZgbQLu_PXZmA27q7vHygg\n\nJASMIN Notebooks workshop tutorial: https://www.youtube.com/watch?v=7UWjhIKq2x0\u0026list=PLhF74Yhqhjqn8NDgU7xfKGLGP8h-FQ1lt\u0026index=16\n\nNotebook that I showed (demonstrating intake access to CMIP6): https://github.com/cedadev/cmip6-object-store/blob/master/notebooks/cmip6-zarr-jasmin.ipynb\n\nIntake library documentation: https://intake.readthedocs.io/en/latest/?badge=latest\n\nIntake ESM (for Earth System Model data) docs: https://intake-esm.readthedocs.io/en/stable/\n\nKerchunk docs: https://fsspec.github.io/kerchunk/\n\nUseful intro talk on Kerchunk (when it was called ReferenceFileSystem - I think): https://www.youtube.com/watch?v=AWJzDk6M6NM\u0026t=628s\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedadev%2Fkerchunk-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcedadev%2Fkerchunk-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcedadev%2Fkerchunk-tools/lists"}