HABITUSReference Book

12. Map, Help and output files (🗺 Map, ⓘ Help)

Tabs: 🗺 Map, ⓘ Help · Code: tabs/tab_map.py, occurrence_map.py, study_area_figure.py, map_widget.py (figure options), tabs/tab_help.py, run_config.py, main_dialog.py (session log), main.py (crash log)

12.1 What this chapter covers

This chapter covers the two tabs that stand outside the workflow and the topics common to the whole workflow:

Neither tab is locked; they can be used from the moment the program opens (main_dialog.py:194-196). They come after the numbered steps in the tab bar and provide no input to the workflow.

12.2 The place of the 🗺 Map tab

🗺 Map shows on a map what was given to ① Data before any model is built: the presence records, the records excluded before modelling once ① Data has been run, the user's own absence records, the study boundary and the calibration polygon. Its purpose is to see a misplaced record, swapped coordinates or a boundary layer that does not overlap the region before modelling (tabs/tab_map.py:1-11).

Each time the tab becomes visible, it rebuilds the map if the inputs have changed (tabs/tab_map.py:141-169). Model results are not shown here; the current and future maps are in the map viewer of the ③, ⑤ and ⑥ tabs (Chapters 6, 8, 9).

12.3 The 🗺 Map tab

At the top of the screen are the layer checkboxes and two buttons, below them a status line, and below that the map (tabs/tab_map.py:100-139). The map is drawn inside a web view with the Leaflet library; Leaflet ships with the program, while the basemap tiles are downloaded from tile.openstreetmap.org (occurrence_map.py:45-50, 92-95).

Figure 12.1. The 🗺 Map tab in the sample run after ① Data has been run: four layer checkboxes at the top, ↻ Refresh and 💾 Save study-area figure… on the right; below them the status line "626 occurrence record(s) shown · 405 excluded"; on the OpenStreetMap basemap, blue presence records and excluded records as hollow grey circles; the layer list at top right and the scale bar at bottom left.
Figure 12.1. The 🗺 Map tab in the sample run after ① Data has been run: four layer checkboxes at the top, ↻ Refresh and 💾 Save study-area figure… on the right; below them the status line "626 occurrence record(s) shown · 405 excluded"; on the OpenStreetMap basemap, blue presence records and excluded records as hollow grey circles; the layer list at top right and the scale bar at bottom left.
Name in the UI What it does Default Range / options Code
Occurrences Shows the presence records in the CSV; in a multi-species file each ticked species in a separate colour on on / off tabs/tab_map.py:108, 179-214
Excluded occurrences Shows, with their reasons, the records excluded before modelling once ① Data has been run on on / off tabs/tab_map.py:109-113, 216-225
Own absences Shows the absence CSV given in the Own Absences sub-tab as black points on on / off tabs/tab_map.py:114, 227-243
Boundary / calibration area Draws the study boundary (red) and the calibration polygon (purple, dashed) on on / off tabs/tab_map.py:115, 245-263
↻ Refresh Rebuilds the map from the inputs — button tabs/tab_map.py:120-122
💾 Save study-area figure… Saves a location map for publication from the ticked layers — button; §12.3.2 tabs/tab_map.py:123-130, 268-311

When one of the checkboxes changes, the map is redrawn immediately (tabs/tab_map.py:116-117). These checkboxes affect only the display and the saved figure; they do not change the data entering the modelling.

12.3.1 Contents of the layers

The status line reports the number of records shown and excluded, the records without valid coordinates and the layers that could not be drawn. For a CSV that cannot be read, the message "The map could not be built: …" appears instead of the map (tabs/tab_map.py:154-169).

Note: The basemap tiles require a network connection. Without a connection the points and polygons are still drawn and the basemap remains blank. The program identifies itself to the OpenStreetMap tile server as "HABITUS/<version>" (occurrence_map.py:7-11, 53-58). If the web view component (PyQt6-WebEngine) is not installed, the tab shows the message "The map needs PyQt6-WebEngine, which is not installed (pip install PyQt6-WebEngine)." (occurrence_map.py:138-145).

12.3.2 Save study-area figure… (study area figure)

This button draws the ticked layers of the map, independently of the web view, as a location map that can be placed in a paper (study_area_figure.py:1-10). The OpenStreetMap tiles on screen are at screen resolution and carry their own licence terms; the saved figure instead uses the Natural Earth country boundaries (public domain) shipped with the program and needs no network.

Pressing the button first opens the "Figure for publication" options window, then the save dialog (tabs/tab_map.py:268-311).

Name in the UI What it does Default Range / options Code
Width: Width of the figure (journal column widths) Double column — 174 mm Single column — 85 mm, 1.5 column — 120 mm, Double column — 174 mm map_widget.py:112-116, 193-196; tabs/tab_map.py:139
Resolution: Resolution for raster formats (PNG, TIFF, JPEG) 600 dpi 300, 600, 1200 dpi; not used for PDF, SVG, EPS map_widget.py:117, 197-203
Title: Title text names of the ticked species, otherwise the species name free text tabs/tab_map.py:283-288, map_widget.py:209-212
Include the title above the map Writes the title above the map off on / off tabs/tab_map.py:139, map_widget.py:204-206
Italic title (scientific name) Writes the title in italics on if there is a species name on / off tabs/tab_map.py:289
Locator map in the upper-left corner Adds a small locator map showing the study extent in the upper-left corner on on / off tabs/tab_map.py:290, study_area_figure.py:265-290
File type in the save dialog The format is determined from the file extension PNG PNG, TIFF (LZW-compressed), PDF, SVG, EPS (vector), JPEG (quality 95) map_widget.py:156-177

The suggested file name is <species>_study_area.png in the output folder (tabs/tab_map.py:294-300). The window remembers the last choices during the session (tabs/tab_map.py:293).

The figure consists of the following elements (study_area_figure.py:190-262, 293-313):

12.4 The ⓘ Help tab

ⓘ Help is a user guide embedded in the program, in English only (tabs/tab_help.py:1000-1017). The top bar holds the update buttons, with twelve page tabs below it (tabs/tab_help.py:1027-1101).

Figure 12.2. The ⓘ Help tab, Overview page: the Check for Updates button at top right, the twelve page tabs below it; on the page, "What is HABITUS?", the eight-step "Typical Workflow" and the "Supported Algorithms" table.
Figure 12.2. The ⓘ Help tab, Overview page: the Check for Updates button at top right, the twelve page tabs below it; on the page, "What is HABITUS?", the eight-step "Typical Workflow" and the "Supported Algorithms" table.
Page Contents
Overview Description of the program, the eight-step workflow, the algorithm table and the required libraries, quick start
1 Data Presence CSV, rasters, background and pseudo-absence settings, output folder
2 Variables VIF and correlation, colour codes, confirmation
2b Advanced Analysis Condition number, PCA, LASSO, Ridge and how to read them together
3 Models Algorithm selection, minimum-record recommendations, training settings, rationale of the cross-validation design, two-level ensemble, performance metrics, current map
4 Evaluation Sub-tabs, ROC, variable importance, response curves, threshold methods
5 Future Scenario name, algorithm selection, adding future rasters
6 Range Change Result codes (-2, 0, 1, 2), file selection, reading the result table
7 Validation Map selection, reclassification, sampling, metrics, export, interpreting Kappa
8 Report Report sections, generation and export, ODMAP protocol, map quality
FAQ Common errors, performance tips, output files table
About Version, developer, citation, licence (GNU GPL version 3), core dependencies, update status
Figure 12.3. ⓘ Help > FAQ page: common error messages and their solutions under the "Errors" heading, "Performance Tips" and the beginning of the "Output Files" table.
Figure 12.3. ⓘ Help > FAQ page: common error messages and their solutions under the "Errors" heading, "Performance Tips" and the beginning of the "Output Files" table.
Figure 12.4. ⓘ Help > About page: the heading "HABITUS v2.1.0", the result of the update check ("You are using the latest version"), developer, citation and DOI, licence, core dependencies.
Figure 12.4. ⓘ Help > About page: the heading "HABITUS v2.1.0", the result of the update check ("You are using the latest version"), developer, citation and DOI, licence, core dependencies.
Name in the UI What it does Default Range / options Code
Check for Updates Manually asks whether there is a new version on the release page; the result appears on the About page — button tabs/tab_help.py:1052-1059, 1142-1152
Download Update Appears when a new version is found; downloads the installer for this computer to the Downloads folder hidden button tabs/tab_help.py:1062-1071, 1154-1248

The program performs the update check automatically, in the background, at start-up; it does not do so if the environment variable HABITUS_NO_UPDATE_CHECK is defined (main_dialog.py:130-143). The query goes to the GitHub release page and is abandoned if no response arrives within 10 seconds (updater.py:88-94). The About page shows the result of the check in a banner: "Checking for updates...", "You are using the latest version (v…)", "Update Available - v…" or "Update check failed: …" (tabs/tab_help.py:1103-1140). If a new version is found, a line is also written to the log panel (main_dialog.py:145-148).

Download Update downloads the installer but does not install it: "Close HABITUS and run it to install the update. Your settings and results are not touched." (tabs/tab_help.py:1212-1218). If the download fails, the address of the release page is given.

Note: The Help pages are a short reference guide. For exact details (default values, file names) this book should be taken as authoritative; for example, the actual names of the output files are in §12.5.

12.5 File catalogue of the output folder

All outputs go to the ① Data > Output Directory folder (or to the folder entered in ③ Models) (Section 1.9). In a multi-species file each species is in its own subfolder; that subfolder carries the same tree as below, while the parent folder holds batch_summary.csv and (if there is a boundary) masked_inputs/current/.

The <species> prefix in file names: in projection, report and figure files, spaces in the species name are converted to underscores (abies_nordmanniana_current_EMwmean_prob.tif); in the range change file the species name stays as it is (abies nordmanniana_SSP585_2090_SRC.tif) (sdm_core.py:7655-7656, tabs/tab_range.py:213-216). If the species name is unknown, no prefix is added.

The tree below is taken from the folder of the sample run and completed from the code:

<output folder>/
  habitus_run_config.json             ③ run record
  evaluation_scores.csv               ③ (+ evaluation_scores.<time>.bak.csv)
  .habitus_state.json                 summary for the CSV backup check
  occurrence_train.csv                ③ training presences
  occurrence_test.csv                 ③ test presences
  occurrence_all_splits.csv           ③ both together
  occurrences_used.csv                ① multi-species file only
  accessible_area.tif                 ① accessible area
  background_maxent.csv               ① optional
  <species>_<YYYYMMDD_HHMMSS>.log     session log
  <species>_HABITUS_report_<time>.html ⑧ report
  odmap_protocol.md / .csv            ⑧ via the ODMAP button
  <species>_<analysis name>_SRC.tif   ⑥ range change
  <species>_study_area.png            🗺 optional
  masked_inputs/current/              ① rasters clipped to the boundary
  masked_inputs/<scenario>/           ⑤ scenario rasters clipped to the boundary
  current/                            ③ current-climate maps
  <scenario>/                         ⑤ future maps
  figures/                            ② ④ figures and tables
  advanced_analysis/                  ② Advanced Analysis export
  tuning/tuning_<algorithm>.csv       ③ Tuning
  validation/                         ⑦ reclassified rasters
File Which step Contents Code
accessible_area.tif ① Data Accessible area mask from which the background is drawn; not written if Accessible area is none. Used by ⑥ Range Change tabs/tab_data.py:1540-1545
background_maxent.csv ① Data MaxEnt background points and their environmental values (if requested in the MaxEnt sub-tab) tabs/tab_data.py:1550-1559
occurrences_used.csv ① Data In a multi-species file, the records of this species only tabs/tab_data.py:1503
masked_inputs/current/, masked_inputs/<scenario>/ ① Data, ⑤ Future Raster copies clipped to the study boundary tabs/tab_data.py:1520, tabs/tab_projection.py:607
figures/correlation_heatmap.png, correlation_heatmap_selected.png, vif_barplot.png ② Variables Correlation heat map (all and selected variables), VIF plot tabs/tab_vif.py:1007, 1151, 1278
figures/high_correlation_pairs.csv, figures/variable_priority_ranking.csv ② Variables Highly correlated pairs; VIF and priority ranking tabs/tab_vif.py:1056, 1091
advanced_analysis/ ② Advanced Analysis pca_variance.png/.csv, pca_loadings.csv, lasso_coefficient_paths.png, lasso_coefficients.csv, lasso_path.csv, ridge_coefficient_paths.png, ridge_coefficients.csv, ridge_path.csv tabs/tab_vif_advanced.py:769-882
current/<species>_current_<ALGO>_PA<n>_prob.tif, _bin.tif ③ Models Probability (0-1) and binary (0/1) map for each algorithm and pseudo-absence set sdm_core.py:7895, 7911
current/<species>_current_<ALGO>_mean_prob.tif, _mean_bin.tif, _sd.tif ③ Models Mean and standard deviation of the within-algorithm replicates sdm_core.py:7981-8005
current/<species>_current_EMwmean_prob.tif, EMca_prob.tif (and _bin) ③ Models Ensemble: weighted mean and committee averaging sdm_core.py:8083, 8098
current/<species>_current_EMsd.tif ③ Models Spread among ensemble members (not thresholded) sdm_core.py:8056-8066
current/<species>_current_NT1.tif, NT2.tif, MIC_NT1.tif, MIC_NT2.tif ③ Models Extrapolation diagnostic (ExDet) and most influential variable sdm_core.py:7205-7215
current/<species>_current_projection_options.json ③ Models Projection options (clamp, MESS) and grid alignment summary sdm_core.py:7655-7662
evaluation_scores.csv (a copy in figures/) ③ Models, ④ Evaluation ROC-AUC, TSS, Boyce, Kappa etc. for each model and ensemble; the Score_source column states the source of the score tabs/tab_evaluation.py:1073-1107
occurrence_train.csv, occurrence_test.csv, occurrence_all_splits.csv ③ Models Training and test points with the columns longitude, latitude, presence, split tabs/tab_models.py:1915-1955
habitus_run_config.json ③ Models Run record (§12.6) tabs/tab_models.py:1640-1657
tuning/tuning_<algorithm>.csv ③ Tuning Grid search table tabs/tab_tuning.py:408-413
figures/evaluation_model_scores.png, evaluation_roc_curves.png, evaluation_omission_pr_calibration.png/.csv, evaluation_variable_importance.png, evaluation_response_<ALGO>.png, evaluation_boyce_<ALGO>.png ④ Evaluation Evaluation figures (300 dpi) and the omission-calibration table tabs/tab_evaluation.py:353-847, 923-937
figures/classification_thresholds.csv ④ Evaluation Thresholds found by each threshold method and hold-out performance tabs/tab_evaluation.py:1323
<scenario>/<species>_<scenario>_…tif ⑤ Future The same family of files as current/, with the scenario name sdm_core.py:7895-8138
<species>_<analysis name>_SRC.tif ⑥ Range Change Change map: -2 loss, 0 stable absence, 1 stable presence, 2 gain tabs/tab_range.py:213-216
validation/Reclassify_ref_<name>.tif, Reclassify_val_<name>.tif ⑦ Validation Reclassified reference and model maps tabs/tab_validation.py:728-730, 819-830
validation_report_<time>.txt/.json/.html, validation_points_<time>.csv ⑦ Validation Validation report and sample points, if the user saves them tabs/tab_validation.py:970-1005
<species>_HABITUS_report_<time>.html ⑧ Report Single-file HTML report; the figures are embedded in the file tabs/tab_report.py:2507-2510
odmap_protocol.md, odmap_protocol.csv ⑧ Report Partially filled ODMAP protocol odmap.py:647-686
batch_summary.csv ⑧ Report (batch) Per species: status, failed step, error, folder, duration batch_species.py:280
<species>_<YYYYMMDD_HHMMSS>.log all steps Session log (§12.7) main_dialog.py:612-645

Raster format. Projection rasters are GeoTIFF, float32, NoData value -9999 (sdm_core.py:7205-7215). Probability maps are in the range 0-1. In the current/ folder of the sample run, 37 map files were written for four algorithms (Figure 1.3).

Caution: A new run overwrites the files in the output folder; files left from a previous run and not produced in the new run are not deleted (Section 1.6.2). If evaluation_scores.csv has been edited by hand, it is backed up as <name>.<YYYYmmdd_HHMMSS>.bak.csv before being overwritten; for this, a summary of the file's last write is kept in the .habitus_state.json file (sdm_core.py:6752-6800).

12.6 Run record: habitus_run_config.json

The run record gathers the information needed to reconstruct an analysis in a single machine-readable file (run_config.py:1-14). Each time ③ Models runs, it is written to the root of the output folder after modelling has finished (tabs/tab_models.py:1640-1657, run_config.py:154-163).

12.6.1 Top-level fields

Field Contents Sample run Code
habitus_version Program version "2.1.0" run_config.py:140
random_seed Seed of the run 42 run_config.py:141
started, finished Time the record was created and written (ISO format) both "2026-11-21T05:11:12" run_config.py:97-98, 142-143
settings Settings section by section (§12.6.2) 9 sections run_config.py:144
setting_source Source of each setting: default, user or recorded 36 default, 2 user, 44 recorded run_config.py:79-92, 105-119
defaults_left_unchanged List of settings left at their defaults: {section, setting, value} 36 items run_config.py:127-134, 146-149
notes ADVISORY: notes and the cross-validation summary 4 lines run_config.py:121-125
environment Python version, operating system, processor architecture, versions of the scientific packages Python 3.13.1, Windows 11, AMD64, numpy 2.4.6, scikit-learn 1.8.0, elapid 1.0.4 … run_config.py:61-74

started and finished are not the start and end of the modelling job; they show the moment the record was created and written. The duration of the job is read from the time stamps in the session log.

Setting source. The code compares each recorded value with the program's default (run_config.py:105-119):

The defaults_left_unchanged list is also printed explicitly in the report; thus no default enters a publication without the user being aware of it (run_config.py:87-91).

12.6.2 settings sections

Section Main fields Chapter
data presence file, species, numbers of records used and excluded and the reasons, one record per cell, rasters, raster grid (shape, cell size, CRS), prevalence 2
background absence source (pseudo, user, user+pseudo), strategy, numbers of replicates and points, MaxEnt background, sampling bias correction 3
study_area accessible area method, buffer, percentage of the extent, calibration layer 3
study_boundary boundary layer, number of polygons, clipped grid 2
thinning whether thinning was applied, distance, records kept and dropped 3
spatial_structure spatial autocorrelation range and method, study extent 5
cross_validation design, requested number of folds, block size, the design actually used in each pseudo-absence set (per_pa_set) 5
models algorithms and all their options, threshold method, Boyce formula, variables, clamp, categorical variables, class weight 5-6
ensemble ensemble method, minimum score, weights, surfaces written, hold-out ensemble scores 6
tuning_<algorithm> If Tuning was done, the grid, the rule and the selected point 6

From the sample run: data.n_presences_used 143, data.n_points_dropped 483, data.prevalence 0.125; in notes, "Cross-validation: PA1: spatial_block, 4 fold(s), blocks of 151.5 km [SSB=0.36] | PA2: …".

Note: The file is written when ③ Models finishes. The settings of later steps are not here: the projection options are in the <species>_<scenario>_projection_options.json file in each scenario folder; the ⑥ Range Change and ⑦ Validation settings are in the session log and the report. The program's internal constants (e.g. fixed values other than the ranges of the Tuning grid) are not written to the record; the record contains the values collected from the UI and passed to the computation engine.

12.6.3 The run record and ODMAP

ODMAP (Overview, Data, Model, Assessment, Prediction) is the standard protocol proposed for reporting species distribution models (Zurell et al., 2020). The ODMAP button in ⑧ Report fills in the elements of the protocol by reading the run record (odmap.py:1-22, 155-200; Chapter 11):

In short, the run record is the source of the protocol; the ODMAP file is a readable, standard-format summary of the record. The protocol does not count as an "ODMAP-compliant report" until the user completes the missing elements.

12.7 Logs

12.7.1 Session log

From the moment the output folder is known, every line of the log panel is also written to the <species>_<YYYYMMDD_HHMMSS>.log file in the folder (Section 1.7; main_dialog.py:612-645, 790-801). The file contains:

The log of the sample run (habitus_20261121_050108.log) begins as follows: "[05:01:08] Reading raster 1 of 19: bio_1.tif" … "[05:01:09] ⚠ 405 of 626 presence records removed (405 in a cell that already has a record) — 221 retained, one per raster cell." … "[05:01:09] Spatial autocorrelation range = 151.5 km (variogram)." ⑧ Report appends the log file in the output folder to the last section of the report (tabs/tab_report.py:607-616).

12.7.2 Crash log

If the program closes before it can show an error window (a native crash or an uncaught error), the cause is written to the crash log in the user data folder (main.py:253-290):

Platform Folder
Windows %LOCALAPPDATA%\HABITUS\logs\
macOS ~/Library/Application Support/HABITUS/logs/
Linux $XDG_DATA_HOME/HABITUS/logs/, or ~/.local/share/HABITUS/logs/ if the variable is not set

There is one file per day (crash_YYYYMMDD.log); each start-up adds a line with the version number and time. In a native crash, the Python stack of all threads at that moment is written. When reporting a crash, this file should be sent together with the session log.

12.8 Environment variables

Environment variables are defined in the operating system before the program is started. None of them is needed in ordinary use.

Variable Effect Default Code
HABITUS_UI_SCALE Proportionally enlarges or shrinks the UI text and controls 1.0; a value outside 0.5-3.0 or an invalid value is taken as 1.0 ui_style.py:30-38
HABITUS_PROJECTION_TILE_CELLS Number of cells in a strip when projecting large rasters; 0 turns striping off. A raster smaller than twice this value is processed in one piece 2000000 sdm_core.py:7512-7526
HABITUS_NO_UPDATE_CHECK Any non-empty value turns off the update check at start-up (offline environment) undefined main_dialog.py:131-132
HABITUS_SAFE_GRAPHICS Linux launch scripts only: if 1, software rendering is enabled (if windows open blank) undefined scripts/make_linux_archive.sh:71-75
QT_QPA_PLATFORM Linux scripts: in a Wayland session, xcb (XWayland) is selected if it is not defined; the user's value is kept set by the script scripts/make_linux_archive.sh:63-66
QTWEBENGINE_DISABLE_SANDBOX Linux scripts set it to 1 so that the web view of the Map tab can run from the portable folder set by the script scripts/make_linux_archive.sh:67-70
PROJ_DATA, PROJ_LIB If they do not point to a valid coordinate database, the program sets them to its own copy at start-up checked by the program main.py:110-163
PYTHONHASHSEED If not defined, set to the run seed when ① Data runs seed run_config.py:49
HABITUS_OWNER_PID Internal use: the running program writes its own process number; helper processes derived from it do not open a second window. Should not be set by hand written by the program proc_guard.py:46, 86-122

12.8.1 HABITUS_PROJECTION_TILE_CELLS

12.9 Troubleshooting

The full error text is obtained with the Copy full message button in the error window and is found in the session log (Section 1.7). The messages below are taken from the code (their beginnings are given).

Message Cause Solution Code
"Please specify an output directory." Output Directory is empty Select a folder, or first select a CSV and wait for the automatic folder tabs/tab_data.py:1370-1371
"Environmental rasters are not on the same grid." One of the rasters differs from the first raster in size, cell size, origin or CRS; the message names the differing file Bring the rasters to a common grid in a GIS program or give a study boundary (Chapter 2) sdm_core.py:1735-1742
"No continuous environmental rasters were given." Only categorical rasters were added Add at least one continuous raster sdm_core.py:1554
"Only N valid presence point(s) remain after removing …" Most records are outside the raster or on NoData; usually the CSV and the rasters have different coordinate systems Check the coordinate system and the longitude-latitude order; look at the records in 🗺 Map sdm_core.py:2028-2036
"No presence record can be used: the layer(s) … have no value (NoData) …" The named layer is NoData at all records Check the layer or remove it sdm_core.py:2021
"N of M coordinate pair(s) are not valid degrees" Coordinates in metres or columns reversed Correct the CSV sdm_inputs.py:192
"Only one predictor is loaded …" A single continuous raster Add rasters in ① Data tabs/tab_vif.py:369
"… is too small for N requested points: the background was drawn from the FULL raster extent instead." The accessible area is too narrow for the requested number of points Enlarge the buffer or reduce the number of points sdm_core.py:2845
"Calibration polygon: NONE of the N presence records lies inside the polygon(s)." The polygon is in another region or another CRS Check the polygon sdm_core.py:2657
"WARNING: … were merged into others …" The block design could not provide the requested number of folds Reduce the number of folds or the block size (Chapter 5) sdm_core.py:5131
"WARNING (design not applied): …" The requested cross-validation design could not be applied and random folds were used instead; scores may be optimistic Review the design and the distribution of records (Chapter 5) sdm_core.py:5139
"No model passed the ensemble threshold …" No model passed the threshold for entering the ensemble Lower the minimum score or choose another metric (Chapter 6) tabs/tab_models.py:1732
"No Full models found for selected algorithms." The selected algorithms failed in training Look at the FAILED lines in the log; check that the library is installed sdm_core.py:7859
"Raster count mismatch! …" The number of future rasters does not match the model's variables Check the scenario folder and the file names (Chapter 8) tabs/tab_projection.py:527
"Cannot find raster files for N selected variable(s)" Scenario file names do not match the variable names Match the file names to the names in ② Variables tabs/tab_models.py:1435
"Complete the workflow for one species first …" For a batch run, ①-③ must first be completed for one species Run one species to the end (Chapter 11) tabs/tab_report.py:481
"ODMAP protocol: No output folder yet. Run the models first." No output folder Run ③ Models first tabs/tab_report.py:554
"… still running — close anyway?" The window is being closed while a job is running Yes cancels the job; wait for it to finish main_dialog.py:293-301
"Unable to allocate …" / "MemoryError" Insufficient memory Clip the rasters, reduce the number of points, reduce HABITUS_PROJECTION_TILE_CELLS error_dialog.py:39-41
"proj.db lacks DATABASE.LAYOUT.VERSION.MAJOR …" Another installation of the coordinate library interferes The program selects its own copy at start-up; if it persists, remove the PROJ_DATA and PROJ_LIB variables main.py:82-110
"Permission denied" / "being used by another process" The output file is open in another program Close the file and run again error_dialog.py:51-53
"The map needs PyQt6-WebEngine, which is not installed" The web component of the Map tab is missing (running from source) pip install PyQt6-WebEngine occurrence_map.py:140-141
Basemap blank in the Map tab No network connection or the tile server does not respond Check the connection; the points and Save study-area figure… work offline occurrence_map.py:92-95
Windows open blank on Linux Graphics driver problem Start with HABITUS_SAFE_GRAPHICS=1 scripts/make_linux_archive.sh:71-75
Program closed without a message Native crash Send the crash log (§12.7.2) main.py:253-290
Window seems unresponsive A long job is running in the background If the progress bar and the log are updating, wait threads.py

Tip: To test whether an installation is sound, first run --selftest (Section 1.3). The report names missing algorithm libraries and coordinate database problems.

12.10 System requirements

Item Requirement Source
Windows 64-bit Windows 10 (version 1809, build 17763) or later; Windows 11 habitus_setup.iss:33, 44
macOS Separate Apple Silicon and Intel packages; the minimum system version is stated on the package habitus.spec:345-373
Linux 64-bit; distributions with glibc 2.35 or later (the packages take some system libraries, e.g. GL and X11, from the system) CHANGELOG.md, Linux packages
Running from source Python 3.10 or later and the requirements.txt dependencies pyproject.toml:11
Memory There is no lower limit in the code; the memory needed depends on the size and number of rasters. A measured example: 19 global layers (2.5 minutes) occupy about 2.6 GB in memory CHANGELOG.md
Network Not required. Only the basemap tiles of the Map tab and the update check connect to the network occurrence_map.py:92, updater.py:88
Screen The window opens at up to 95% of the screen; on a small screen the tabs scroll. Text can be enlarged with HABITUS_UI_SCALE main_dialog.py:113-121, ui_style.py:30-38

The measure that reduces the memory requirement most is clipping the rasters to the study region with ① Data > Study Boundary (Chapter 2). The run times of the algorithms are written to the session log; before a large analysis, a small trial (one pseudo-absence replicate, few algorithms) helps to estimate the run time.

12.11 Expert questions

Q1. Can another researcher reconstruct this study from the output folder alone? Answer: Largely. habitus_run_config.json carries the seed, the paths of the input files, all UI settings, the cross-validation design actually applied and the package versions (run_config.py:137-152; tabs/tab_models.py:2056-2242). The input files themselves are not copied into the folder (except the copies clipped with the study boundary, masked_inputs/); only their paths are written. No checksum proving that the content of the rasters has not changed is written to the record. The projection settings are in separate projection_options.json files. For full reconstruction the input data must be archived separately.

Q2. Why is defaults_left_unchanged a separate list? Answer: To separate which numbers in a publication were chosen deliberately and which remained as the program's defaults. The code compares each setting with its default and puts those equal to the default into this list (run_config.py:105-134); the report prints this list. In the sample run 36 settings are at their defaults. A reviewer can use this list to ask, for example, whether the number of pseudo-absences (1000) or the number of folds was justified.

Q3. What does the recorded source mean, and how does it differ from user? Answer: user is only for settings that have a default and that the user changed. Values without a default (input files, the block size computed during the run, prevalence, number of records used) are marked recorded (run_config.py:79-92, 113-118). Thus a computed number does not look like a user choice. In the sample run 44 values are recorded and 2 are user.

Q4. Does the run record replace an ODMAP report? Answer: No. ODMAP (Zurell et al., 2020) includes elements the program cannot know, such as authorship, objective, hypotheses and data sources. odmap.py fills in the elements that have a counterpart in the record as auto, leaves the others as user_required and does not invent any value (odmap.py:14-22, 153-154). According to the code comment, the elements are those of Table 1 of the paper; the detailed question list in the supplementary table was not used as the basis (odmap.py:11-14). The user must complete the user_required rows.

Q5. Can the output maps be used directly in another GIS program; how are the values interpreted? Answer: Yes; they are written as GeoTIFF, float32, NoData -9999 and carry the coordinate system of the source rasters (sdm_core.py:7205-7215). The _prob files are suitability in the range 0-1; this is not a probability of occurrence, because prevalence is unknown in models built with pseudo-absences (Elith and Leathwick, 2009). The _bin files are 0/1 maps obtained with the selected threshold; the threshold method is in the models.binary_threshold_method field. The EMsd and _sd surfaces are not suitability but disagreement between models and are not thresholded (sdm_core.py:8056-8066).

Q6. Is there a difference between the map display on screen and the saved GeoTIFF? Answer: Files such as PNG and PDF produced by the viewer and by Save study-area figure… are images; they include a colour scale, a scale bar and aspect-ratio correction and should not be used for analysis. Numerical analysis is done with the GeoTIFFs in current/ and the scenario folders. When the points in the Map tab exceed 20,000 they are decimated for display only (tabs/tab_map.py:22-24); modelling is not affected by this decimation.

Q7. When the program writes to the same folder a second time, how do I distinguish the old results? Answer: The program does not delete old files; it overwrites those with the same name. Ways to distinguish them: the finished time of the run record, the time-stamped name of the session log and the time-stamped name of the report. evaluation_scores.csv is backed up if it was changed by hand (sdm_core.py:6764-6800); other files are not backed up. For comparative runs, giving each run a separate folder is the only reliable way (Section 1.9).

Q8. Is the effect of the software environment (package versions) on the result recorded? Answer: Yes, the environment field records the Python version, operating system, architecture and the versions of numpy, pandas, scipy, scikit-learn, rasterio, matplotlib, xgboost, lightgbm, catboost, pygam, elapid and PyQt6 (run_config.py:61-74). Whether the same result can be expected with the same seed depends on these versions also being the same; a different scikit-learn or elapid version can give different numbers with the same seed. Because the packaged program pins the versions, repeating with the same package version is the most reliable way.

Q9. How accurate are the scale bar and aspect ratio in the study area figure? Answer: The figure does not use a projection; the longitude-latitude axes are drawn with an aspect-ratio correction by the cosine of the mid-latitude (study_area_figure.py:229-232). The scale bar uses the method of the map viewer (study_area_figure.py:241). This is an adequate approximation for small and medium-sized areas; over wide latitude ranges (e.g. continental scale) the scale bar is correct only for the mid-latitude. If an equal-area projection is required, the figure should be redrawn in a GIS program.

Q10. What information does the update check send out; can the program be used offline? Answer: The check requests only the information on the latest release on GitHub (updater.py:88-94); no analysis data are sent. When downloading basemap tiles, the Map tab sends the program's name and version as its identifier (occurrence_map.py:53-58). The program works offline; the update check can be turned off with HABITUS_NO_UPDATE_CHECK (main_dialog.py:131-132), and in the Map tab only the basemap is missing.

12.12 Common mistakes and pitfalls

12.13 References

Elith, J., Leathwick, J.R., 2009. Species distribution models: ecological explanation and prediction across space and time. Annual Review of Ecology, Evolution, and Systematics 40, 677-697. https://doi.org/10.1146/annurev.ecolsys.110308.120159

Zurell, D., Franklin, J., König, C., Bouchet, P.J., Dormann, C.F., Elith, J., et al., 2020. A standard protocol for reporting species distribution models. Ecography 43, 1261-1277. https://doi.org/10.1111/ecog.04960