Adding ItemCollection to PySTAC

[matthewhanson]

An Item Collection is defined in pystac-api-client, which will be updated to use the Item Collection extension.

The Item Collection is used for API responses which can then be saved as GeoJSON ItemCollections. Having this defined in pystac-api-client makes sense because it's used in the API and is not a core STAC object.

However, I'm thinking of creating some additional libraries that I want to operate either on STAC catalogs OR on a saved FeatureCollection. The ability to open an ItemCollection and iterate through items, retrieve the parent of collection of an item, or even save as a regular catalog would be very helpful.

Basically I want to be able to use PySTAC features to work with STAC objects, including Item Collections, but I don't have a need for an API client library because it wouldn't use anything else in that library, it just wants to use STAC objects. Seems like it would be cleaner to implement this in PySTAC rather than require libraries to include a dependency to the api client to get the ItemCollection implementation.

[duckontheweb]

I would support including Item Collections in PySTAC. I know that in the current specs it is only used in an API, but there could be other uses of it within the core spec or within other extensions that aren't tied to the API (in addition to @matthewhanson 's use-case above). Putting it in PySTAC would let us take advantage of all the validation, links, and other convenience methods a little more cleanly.

[lossyrob]

While I do think valuing keeping to the spec will help with clarity and to future-proof things, all of the points made here are very convincing. 👍 I think we should do it.

[matthewhanson]

In thinking more about this I think that ItemCollection should not be a STAC object as I had previously suggested, so it wouldn't have stac_version, hierarchical links, stac_extensions, etc. Instead I think it's best as a simple container, straight GeoJSON FeatureCollection that holds STAC Objects (items).

I see an ItemCollection as useful in PySTAC as a utility class. It should be able to:

• save/load ItemCollections, setting each feature as a PySTAC Item
• iterate through Items via get

Then I see convenience functions for going from a catalog branch -> ItemCollection and converting an ItemCollection to a static structure.

I stripped down the class @duckontheweb initially created of all API features and created a branch with an initial implementation: https://github.com/stac-utils/pystac/blob/mah/itemcollection/pystac/item_collection.py

For now, we're also including it in pystac-api-client https://github.com/stac-utils/pystac-client/blob/main/pystac_client/item_collection.py

[duckontheweb]

...ItemCollection should not be a STAC object as I had previously suggested, so it wouldn't have stac_version, hierarchical links, stac_extensions, etc.

I agree. Since it's now an extension and not part of the core, having the stac_version doesn't seem meaningful (and may just be confusing). It seems like the only link we would ever really need in an Item Collection is the next link, so doing away with hierarchical links also makes sense to me.

It should be able to:
...

• iterate through Items via get

I'm not sure I understand this part. Is this referring to making GET requests to fetch the next page of items? If so, it seems like at a minimum it also needs to support the extended Link object described in the Paging docs, and is flexible enough to handle other types of next links since the spec doesn't restrict APIs to a single type of implementation.

For now, we're also including it in pystac-api-client https://github.com/stac-utils/pystac-client/blob/main/pystac_client/item_collection.py

This sounds fine for now, but is the plan to eventually only have it in PySTAC? I don't think it makes sense to maintain it in 2 places long term, so we should make sure whatever gets implemented in PySTAC also works for the pystac-api-client use-cases.

[TomAugspurger]

Was this closed by #430?

[duckontheweb]

Was this closed by #430?

Yes, thanks.

[soxofaan]

(cross-post of stac-extensions/stac-extensions.github.io#24 (comment))

I'm looking into the background of pystac's ItemCollection but didn't find much working pointers.
The original post of this ticket has a reference to https://github.com/stac-extensions/item-collection, but that gives a 404 for me at the moment. Has this repository been fully removed or has it been moved elsewhere?

[jsignell]

I'll cross-post the answer too :)

ItemCollection is defined by the STAC API spec. This is the relevant spec doc: https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/fragments/itemcollection/README.md. It would be great to add a link to that in the pystac ItemCollection docstring if you want to open a PR!