{"id":13735299,"url":"https://github.com/stac-utils/xpystac","last_synced_at":"2025-10-12T04:32:58.232Z","repository":{"id":84595776,"uuid":"594216541","full_name":"stac-utils/xpystac","owner":"stac-utils","description":"For extending xarray.open_dataset to accept pystac objects","archived":false,"fork":false,"pushed_at":"2025-09-18T19:46:19.000Z","size":6435,"stargazers_count":41,"open_issues_count":5,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-09-18T22:00:49.970Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/stac-utils.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-01-27T21:51:00.000Z","updated_at":"2025-09-18T19:44:37.000Z","dependencies_parsed_at":"2023-12-18T20:13:25.400Z","dependency_job_id":"791428b4-120c-483a-b7e3-e47ed92bd187","html_url":"https://github.com/stac-utils/xpystac","commit_stats":{"total_commits":25,"total_committers":2,"mean_commits":12.5,"dds":"0.040000000000000036","last_synced_commit":"8ef17bf4ed72ffa6af1f004c0046dd496f251d75"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/stac-utils/xpystac","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fxpystac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fxpystac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fxpystac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fxpystac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stac-utils","download_url":"https://codeload.github.com/stac-utils/xpystac/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stac-utils%2Fxpystac/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279010259,"owners_count":26084719,"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-10-12T02:00:06.719Z","response_time":53,"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-08-03T03:01:05.245Z","updated_at":"2025-10-12T04:32:58.226Z","avatar_url":"https://github.com/stac-utils.png","language":"Python","funding_links":[],"categories":["`Python` processing of optical imagery (non deep learning)"],"sub_categories":["Cloud Native Geospatial"],"readme":"# xpystac\nxpystac provides the glue that allows `xarray.open_dataset` to accept pystac objects.\n\nThe goal is that as long as this library is in your env, you should never need to think about it.\n\n- **Open one asset**: Reads data for an asset pointing to a COG, a zarr store, or a kerchunk reference file.\n- **Open one item**: Reads data for all the assets in a particular item (commonly each COG represents a band).\n - **Open many items**: Reads all the assets in all the items for a particular item collection\niterable of items, or output of pystac_client.Client.search.\n\n## What works\n\n| file format | one asset (item or collection-level) | one item | many items | \n| ----------- | --------- | -------- | ---------- | \n| COG | x | x | x |\n| Zarr | x | | |\n| Kerchunk | x | x* | x* |\n| virtual Icechunk | x | | |\n\n\\* _if stored in item alongside the datacube extension properties_\n\n\n## Install\n\n```bash\npip install xpystac\n```\n\n## Examples\n\n### Open a single asset\n\nRead from a COG\n\n```python\nimport pystac\nimport xarray as xr\n\nitem = pystac.Item.from_file(\n    \"https://raw.githubusercontent.com/stac-utils/pystac/v1.12.2/tests/data-files/examples/1.0.0/simple-item.json\"\n)\nasset = item.assets[\"visual\"]\n\nxr.open_dataset(asset)\n```\n\nRead from a virtual Icechunk store\n\n```python\nimport pystac\nimport xarray as xr\n\ncollection = pystac.Collection.from_file(\n    \"https://raw.githubusercontent.com/stac-utils/xpystac/refs/heads/main/tests/data/virtual-icechunk-collection.json\"\n)\n\n# Get the latest version of the collection-level asset\nassets = collection.get_assets(role=\"latest-version\")\nasset = next(iter(assets.values()))\n\nxr.open_dataset(asset)\n```\n\nHere are a few examples from the [Planetary Computer Docs](https://planetarycomputer.microsoft.com/docs/overview/about) which has some good examples of collection-level assets used to catalog zarr stores and\nkerchunk reference files.\n\n```python\nimport planetary_computer\nimport pystac_client\nimport xarray as xr\n\n\ncatalog = pystac_client.Client.open(\n    \"https://planetarycomputer.microsoft.com/api/stac/v1\",\n    modifier=planetary_computer.sign_inplace,\n)\n```\n\nRead from a kerchunk reference file ([ref](https://planetarycomputer.microsoft.com/dataset/nasa-nex-gddp-cmip6#Example-Notebook)):\n\n```python\ncollection = catalog.get_collection(\"nasa-nex-gddp-cmip6\")\nasset = collection.assets[\"ACCESS-CM2.historical\"]\n\nxr.open_dataset(asset, patch_url=planetary_computer.sign)\n```\n\nRead from a zarr file ([ref](https://planetarycomputer.microsoft.com/docs/quickstarts/reading-zarr-data/))\n\n```python\ncollection = catalog.get_collection(\"daymet-daily-hi\")\nasset = collection.assets[\"zarr-abfs\"]\n\nxr.open_dataset(asset, patch_url=planetary_computer.sign)\n```\n\nNote that this zarr asset uses the xarray-assets extension to store `open_kwargs` and `storage_options` which xpystac can then pass along to `xr.open_dataset`.\n\n### Open a single item\n\nA single item containing many COGs:\n\n```python\nimport pystac\nimport xarray as xr\n\n\nitem = pystac.Item.from_file(\n    \"https://earth-search.aws.element84.com/v1/collections/landsat-c2-l2/items/LC09_L2SR_081108_20250311_02_T2\"\n)\n\nxr.open_dataset(item)\n```\nThis takes advantage of a stacking library (either\n[odc-stac](https://github.com/opendatacube/odc-stac) or [stackstac](https://github.com/gjoseph92/stackstac) - configurable via the `stacking_library` option)\n\n### Open many items\n\nRead all the data from the search results for a collection of COGs:\n\n```python\nimport pystac_client\nimport xarray as xr\n\n\ncatalog = pystac_client.Client.open(\n    \"https://earth-search.aws.element84.com/v1\",\n)\n\nsearch = catalog.search(\n    intersects=dict(type=\"Point\", coordinates=[-105.78, 35.79]),\n    collections=['sentinel-2-l2a'],\n    datetime=\"2022-04-01/2022-05-01\",\n)\n\nxr.open_dataset(search, engine=\"stac\")\n```\n\nRead data from an item collection that uses the exploratory approach of storing kerchunked metadata within the datacube extension metadata:\n\n```python\nimport pystac\nimport xarray as xr\n\nitem_collection = pystac.ItemCollection.from_file(\n    \"https://raw.githubusercontent.com/stac-utils/xpystac/main/tests/data/data-cube-kerchunk-item-collection.json\"\n)\n\nxr.open_dataset(item_collection)\n```\n\n## How it works\n\nWhen you call ``xarray.open_dataset(object, engine=\"stac\")`` this library maps that `open` call to the correct library.\nDepending on the ``type`` of ``object`` that might be a stacking library (either\n[odc-stac](https://github.com/opendatacube/odc-stac) or [stackstac](https://github.com/gjoseph92/stackstac))\nor back to ``xarray.open_dataset`` itself but with the engine and other options pulled from the pystac object.\n\n## Prior Art\n\nThis work is inspired by https://github.com/TomAugspurger/staccontainers and the discussion in https://github.com/stac-utils/pystac/issues/846\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fxpystac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstac-utils%2Fxpystac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstac-utils%2Fxpystac/lists"}