from pylifemap import LifemapGetting started
To create a Lifemap data visualization, you will have to follow these steps:
- Import
Lifemap - Prepare and load your data
- If needed, aggregate you data with an aggregation function
- Initialize a Lifemap object
- Add visualization layers
- show() or save() the result
Import Lifemap
To be able to use pylifemap in a script or notebook you have to import Lifemap from the package:
Prepare your data
The data you want to visualize on the Lifemap tree of life must be in a pandas or polars DataFrame. They must contain observations (species) as rows, and variables as columns, and one column must contain the NCBI taxonomy identifier of the species.
pylifemap includes an example dataset generated from The IUCN Red List of Threatened Species. It is a CSV file with the Red List category (in 2022) of more than 84000 species.
We can import it as a polars or pandas DataFrame with the following code:
import polars as pl
iucn = pl.read_parquet(
"https://raw.githubusercontent.com/Lifemap-ToL/pylifemap/main/data/iucn.parquet"
)import pandas as pd
iucn = pd.read_parquet(
"https://raw.githubusercontent.com/Lifemap-ToL/pylifemap/main/data/iucn.parquet"
)The resulting table only has two columns: taxid, which contains the species identifiers, and status, with the Red List category of each species.
iucn
shape: (84_981, 2)
| taxid | status |
|---|---|
| i32 | str |
| 651506 | "Data Deficient" |
| 2803960 | "Critically Endangered" |
| 143610 | "Critically Endangered" |
| 2760993 | "Least Concern" |
| 72259 | "Least Concern" |
| … | … |
| 337230 | "Least Concern" |
| 442623 | "Vulnerable" |
| 2303643 | "Critically Endangered" |
| 442625 | "Critically Endangered" |
| 442626 | "Least Concern" |
Initialize a Lifemap object
The next step is to create a new Lifemap object. To do this we have to pass it our DataFrame, as well as the name of the column with our taxonomy identifiers1:
Lifemap(iucn, taxid_col="taxid")We could have passed other arguments such as the width and height of our visualization, either as a number of pixels or as a CSS unit.
For example, the following intiialization would make the visualization take the full available width, and an height of 800 pixels.
Lifemap(iucn, taxid_col="taxid", width="100%", height=800)Add visualization layers
After initializing our Lifemap object, we must add visualization layers to create graphical representations.
Here are the available layers:
| Layer | Description |
|---|---|
| layer_points | Displays each observation with a point. Radius and color can be dependent of an attribute in the DataFrame. |
| layer_lines | Using aggregated data, highlights branches of the tree with lines of varying width and color. |
| layer_donuts | Displays aggregated categorical data as donut charts. |
| layer_heatmap | Displays a heatmap of the observations distribution in the tree. |
| layer_heatmap_deck | Displays a deck.gl heatmap of the observations distribution in the tree. |
| layer_screengrid | Displays the observations distribution with a colored grid with fixed-size cells.. |
| layer_text | Displays text labels by taxid |
| layer_icons | Displays icons associated to taxids |
To add a layer, we call the corresponding layer_ method of our Lifemap object. For example, to add a points layer:
Lifemap(iucn, taxid_col="taxid").layer_points()We can add several layers by calling several methods. For example we could display a heatmap layer, and a points layer above it:
Lifemap(iucn, taxid_col="taxid").layer_heatmap().layer_points()Show or save the visualization
Just adding layers is not sufficient to see our visualization. For it to appear, we have to call the show() method:
Lifemap(iucn, taxid_col="taxid").layer_points().show()Warning: 777 taxids have not been found in Lifemap database.
Warning: 152 duplicated taxids have been found in the data.
Note
When in a notebook environment, calling show() will display the visualisation as a widget. When called from a Python script or a Python REPL, the visualization will be saved to a temporary file and, if possible, displayed in the user’s browser. When called from a Python script running inside our Docker container, it will be saved to a file in the working directory.
We can also save it to an HTML file which can be opened later in a browser by using the save() method:
Lifemap(iucn, taxid_col="taxid").layer_points().save("lifemap.html")You can also use the Export to PNG button on the widget to export the currently displayed view to an image file in PNG format.
Customize the layers
Each layer accepts a certain number of arguments to customize its appearance. For example we can change the radius, color and opacity of our points:
(
Lifemap(iucn, taxid_col="taxid")
.layer_points(fill="#EFB118", radius=5, opacity=0.5)
.show()
)Instead of providing fixed values to fill or radius, we can also pass data column names to make size or color depending on the column values. For example, we can make the color of the points depending on their status:
(
Lifemap(iucn, taxid_col="taxid")
.layer_points(fill="status", radius=4, opacity=0.9)
.show()
)Aggregate data
pylifemap provides several functions that allow to aggregate data along the branches of the tree:
| Function | Description |
|---|---|
| aggregate_count | Aggregates the number of children of each tree node. |
| aggregate_num | Aggregates a numerical variable along the tree branches with a given function (sum , mean, max…). |
| aggregate_freq | Aggregates the frequencies of the levels of a categorical variable. |
For example, we could filter our dataset to only keep the species with an “extinct” status:
iucn_extinct = iucn.filter(pl.col("status") == "Extinct")iucn_extinct = iucn[iucn["status"] == "Extinct"]We can then aggregate their count along the branches with aggregate_count:
from pylifemap import aggregate_count
iucn_extinct_agg = aggregate_count(iucn_extinct)
iucn_extinct_agg
shape: (774, 2)
| taxid | n |
|---|---|
| i32 | u32 |
| null | 2 |
| 0 | 196 |
| 2759 | 196 |
| 3193 | 21 |
| 3268 | 1 |
| … | … |
| 3076244 | 1 |
| 3078114 | 76 |
| 3136023 | 1 |
| 3410119 | 1 |
| 3410121 | 1 |
Finally, we can represent this new dataset with a lines layer, making the lines width and color depending on the aggregated count values.
(
Lifemap(iucn_extinct_agg)
.layer_lines(color="n", width="n", label="Extinct species")
.show()
)Warning: 3 taxids have not been found in Lifemap database: [None, 1914395, 3041918].Customize map controls
By default, the Lifemap widgets displays several controls allowing to interact with the map. It is possible to customize which controls are shown by passing a controls argument to Lifemap:
Lifemap(iucn, taxid_col="taxid", controls=("zoom", "full_screen"))The following values are available:
"zoom": zoom in and zoom out buttons"reset_zoom": zoom reset button"png_export": button to export the current view to a PNG file"full_screen": full screen toggle button
Footnotes
if your column is named “taxid” you can omit the
taxid_colargument as it is its default value.↩︎