Troubleshooting

Troubleshooting

Cartopy or Rasterio installation problems

First ensure that pip is current:

python -m pip install --upgrade pip

Then retry:

pip install phylogeoplot

Using a supported Python version and a clean virtual environment is recommended.

Import errors

python -m pip show phylogeoplot
python -c "import phylogeoplot"

If VS Code is being used, make sure the selected Python interpreter corresponds to the environment where the package is installed.

File not found errors

Relative paths are interpreted from the current working directory.

For example:

gps_file="coordinates.csv"

expects coordinates.csv to be available relative to the directory from which Python is executed.

Tree identifiers do not match occurrence data

Tree-tip identifiers must correspond to identifiers in the geographic occurrence data.

See Preprocessing.

Missing coordinates

Occurrence records lacking valid geographic coordinates cannot be mapped.

Verify that latitude and longitude fields contain valid numeric values.

Raster does not align with occurrence data

Check:

• raster coordinate reference system;
• occurrence coordinate system;
• geographic extent;
• longitude and latitude order;
• selected raster band.

Raster appears blank or incorrect

Verify that:

• the GeoTIFF opens correctly in another GIS application;
• the intended raster band is selected;
• the raster contains data within the selected map extent;
• NoData values are handled appropriately.

Overlapping tree labels or lines

Dense trees and long taxon names may create visual overlap.

Offset files can be used to adjust positioning.

Matplotlib graphical backend errors during testing

Automated tests should use a non-interactive Matplotlib backend such as Agg.

Output directory problems

Ensure that the requested output path exists or can be created and that the current user has write permission.

Reporting problems

When reporting an issue, include:

• operating system;
• Python version;
• PhyloGeoPlot version;
• complete error message;
• minimal input example when possible;
• command or Python code that produced the error.