Skip to content

Feat: add interactive map to plasmodium#1177

Open
Kaustubh2k5 wants to merge 5 commits intomalariagen:masterfrom
Kaustubh2k5:feat_add_interactive_map_to_plasmodium
Open

Feat: add interactive map to plasmodium#1177
Kaustubh2k5 wants to merge 5 commits intomalariagen:masterfrom
Kaustubh2k5:feat_add_interactive_map_to_plasmodium

Conversation

@Kaustubh2k5
Copy link

@Kaustubh2k5 Kaustubh2k5 commented Mar 21, 2026

Add plot_samples_interactive_map() to plasmodium API

What problem does this solve?

The plasmodium APIs (Pf8, Pf7, Pv4) had no inbuilt way to visualise sample collection locations. Users had to manually write matplotlib/cartopy code in notebooks to produce a static map. The mosquito API (Ag3, Af1, etc.) has had plot_samples_interactive_map() for some time. so i added a feature in plasmodium class to be able to plot maps

How does it solve it?

Two changes to PlasmodiumDataResource in plasmodium.py:

  • Extended sample_metadata() to accept sample_query and sample_query_options parameters, mirroring the mosquito API. Filtering is applied after the cache lookup so the cached full DataFrame is never poisoned by a filtered call. engine="python" is set by default to handle the spaced column names in plasmodium metadata ("QC pass", "Admin level 1") without requiring backtick syntax from users.
  • Added plot_samples_interactive_map() which renders an ipyleaflet map with one marker per unique first-level administrative division. The method signature matches the mosquito API (sample_query, sample_query_options, basemap, center, zoom, height, width, min_samples, count_by) so users familiar with the mosquito API can use it immediately without reading docs. Key differences from the mosquito version are documented in the method:

Coordinates are GADM admin level 1 centroids (Admin level 1 latitude/longitude) rather than per-sample coordinates, since plasmodium metadata has no finer granularity
count_by defaults to "Population" instead of "taxon"
Tooltip includes an explicit Total samples count (improvement over mosquito version)

Since all three parasite classes inherit directly from PlasmodiumDataResource with no overrides, both methods are immediately available on Pf8, Pf7, and Pv4.

Testing done

Tested on Pf8:

  • Default map renders correctly with markers across Africa, Asia, South America and Oceania
  • sample_query="QC pass== True" filters correctly, reduces marker count
  • sample_query="Country == 'Ghana'" shows single-country view
  • Cache not poisoned sample_metadata() returns full dataset after a filtered call
  • All basemap string options resolve correctly
  • count_by="Year" produces correct year-breakdown tooltips
  • min_samples threshold correctly suppresses low-count locations

Issues closed:

#1175

@Kaustubh2k5 Kaustubh2k5 changed the title Feat add interactive map to plasmodium Feat: add interactive map to plasmodium Mar 21, 2026
@Kaustubh2k5
Copy link
Author

this feature brings the plasmodium APIs more inline with the core mosquito related ones.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant