Add functions to access cohort group metadata

[ahernank]

We have recently started generating metadata files about the cohort themselves, which include cohort size, country code, taxon, administrative units name, ISO code, geoBoundaries shape ID and representative latitude and longitude points & we want to be able to access these ones from the API (for each cohort category/name, i.e. "admin1_month", "admin1_quarter", "admin1_year","admin2_month", "admin2_quarter", "admin2_year")

Additionally, we also produce geojson files for each of the cohort categories (including geometries for each cohort), and we might want to consider accessing these too.

[leehart]

@ahernank check status of geometries on each cohort.

[adilraza99]

Hi @ahernank, @alimanfoo, and @jonbrenas,

I’ve been reviewing Issue #435 and the implementation in PR #436.

From what I understand, CSV-based cohort metadata access via cohorts() was merged, but GeoJSON geometry support was intentionally deferred. The issue remains open, and there are also some follow-up improvements that could strengthen the current implementation (e.g., input validation for cohort_set, caching consistency with other metadata methods, expanded test coverage, and minor path robustness improvements).

To avoid coupling robustness changes with new feature work, I’d like to approach this incrementally.

Proposed plan:

PR 1 – Robustness improvements to cohorts()

• Add explicit validation for accepted cohort_set values.
• Introduce in-memory caching consistent with existing metadata access patterns.
• Improve error messaging for invalid or missing cohort files.
• Expand test coverage across multiple cohort sets and species.
• Address minor path construction fragility.

This would strengthen the existing merged functionality without changing the public API surface.

PR 2 – GeoJSON geometry access

• Propose and discuss an approach for exposing cohort geometries.
• Evaluate dependency implications (e.g., standard library vs optional geopandas).
• Implement geometry access with appropriate tests and documentation.

Before proceeding, I’d welcome your thoughts on whether this staged approach makes sense for moving the issue forward.

If you feel a different structure would be preferable, I’m happy to adjust. Once there’s alignment on the direction, I can begin with the robustness PR.

[jonbrenas]

Thanks @adilraza99, this sounds quite sensible.

[adilraza99]

Thanks @jonbrenas,

While reviewing the history of this issue, I tried to understand what happened with the earlier attempt in PR #1016.

From what I can see, that PR introduced a new AnophelesCohortGroupMetadata class to expose cohort metadata, which effectively created a parallel API rather than extending the existing cohorts() functionality in AnophelesSampleMetadata. Since cohort metadata is already exposed through cohorts() on the Ag3/Af1/Adir1/Amin1 objects, introducing a separate class would mean accessing the same data through two different pathways, which likely explains why the PR was reverted.

Looking at the current implementation from PR #436, the cohorts() method already provides the core functionality, but there are still a few robustness gaps — such as validation of cohort_set, caching repeated CSV reads, clearer error handling, and broader test coverage.

To keep the API consistent, I’m planning to open a follow-up PR that improves the robustness of the existing cohorts() method (validation, caching, optional query filtering, and additional tests) while keeping the public API unchanged.