Heterra guide · Part 1

Getting started with Heterra

From your own data to figures and tables you can put in a paper, one method at a time.

How this guide works

The guide has five parts. This part introduces the software. Parts 2 to 5 are the four groups of methods; each method is one chapter, and every chapter has the same four sections:

Every chapter uses the example that ships with Heterra, so you can repeat each step and compare your screen with the pictures. Several examples use simulated data: their numbers illustrate the tool and do not describe a real study.

Which method answers my question?

Install Heterra

Heterra is free. Download it from the home page.

• Mac (Apple silicon, macOS 13 or later): open the .dmg and drag Heterra to Applications. macOS blocks it the first time: open System Settings → Privacy & Security and choose Open Anyway.
• Windows 10 or 11 (64-bit): double-click the installer. If "Windows protected your PC" appears, click More info, then Run anyway.

No R or Python is needed.

Languages

The interface of Heterra is available in eight languages:

Heterra asks for the language in the welcome window of the first start. If you do not choose, it follows the language of your system, and uses English when the system's language is not one of the eight. To change it later, open Settings → Language, choose and confirm: Heterra restarts in the new language, so save your project first. This guide shows the English interface. Reports are always written in English.

The window

Add your data

Click Add Data, or drop files on the map. Heterra opens Shapefile, GeoPackage, GeoJSON, GeoTIFF, File Geodatabase (.gdb folder) and CSV with coordinate columns.

A table for the methods

Every method works on an attribute table: one row per location (a point, a polygon or a grid cell), one column per variable. Before you start, check three things:

• Numbers are numbers. A column with a stray text cell is read as text, and Heterra tells you which cell. Missing values are empty cells.
• Coordinates are known. For a CSV, choose the two coordinate columns and their coordinate system when you add it (for longitude and latitude: EPSG:4326). Some methods need longitude and latitude, others projected coordinates; each chapter says which.
• Names are simple. Column names and category values are best written with English letters, digits and underscores. This is a recommendation: Heterra also reads other characters.

Data tools

The Toolbox's Data tools prepare a layer without leaving Heterra:

Look at the data first

Select a layer to style it in the panel: single symbol, categories or graduated colours, with RColorBrewer palettes. The Table page shows the attribute table with a summary of every field (count, missing, mean, minimum and maximum), a quick way to find a column that was read as text or has missing values.

Run a method

Every method is run the same way:

1. Open the tool from the Toolbox or the toolbar. Its panel shows a short description and the reference to cite.
2. Try the example first. Click Tutorial, then Load Example: the data are loaded and the settings filled in. Guide opens the example's own notes.
3. Go through the steps. The panel is divided into numbered steps. Next moves on; Run appears only at the steps that compute. Settings that rarely change are under Advanced.
4. Run. If a setting is still missing, a line beside the button says which one and at which step.
5. Read the results. The main figure opens on the Chart page; the panel lists all outputs.

With your own data the steps are the same: add your layer, open the tool (without the tutorial) and choose your layer and fields in step 1.

Checked against RAfter an example runs, a green line in the panel says whether the results match the reference results computed with the method's R implementation. It is a check of the software on your computer; it appears for the examples only.

Find the results

A run gives three kinds of results:

• Figures, on the Chart page. The menu above the figure and the list in the panel switch between them. Most methods have a main figure that opens first.
• Tables, on the Table page.
• New fields or layers, on the Map page: for example the strata of OPGD or a prediction over a grid. They are layers like any other and can be styled and exported.

In a tool's panel, Outputs lists them all; entries that begin with "Figure" or "Table" open that figure or table. Under Results, the panel also writes a few sentences about the run in plain words; a click on a sentence opens the figure it speaks about.

Every run is kept in History (beside Layers), with its settings. Run a method twice with different settings and both results stay available.

Export for a paper

Three points help when a figure goes into a manuscript:

• Prefer vector formats. PDF and SVG stay sharp at any size and can be edited in a drawing program. Use PNG or TIFF when the journal asks for images.
• Keep the data. Save the Data CSV with each figure: reviewers ask for numbers, and you may want to redraw a figure in your own style.
• Use the report as a draft. The report of a run has four parts: method, analysis steps, results (with numbered figures and tables and a sentence of interpretation each), and references. It is a starting text to edit, not a finished section.

Save the project (a .heterra folder) to keep the layers, runs and results together. An unsaved project lives in a temporary folder.

Report and cite

When you write up a result, give the reader what they need to repeat it:

• the data: number of units, the response and the variables;
• the settings you changed from the defaults (every chapter names the ones that matter);
• the software and its version, and the paper of the method.

Cite the software as: Song, Y. (2026) Heterra: Advanced spatial analysis [software]. https://heterra.org

Each tool's panel shows the full reference of its method with a Copy button, and each chapter of this guide ends with the references.

Exercises

Heterra guide, for version 1.6.0. © 2026 Yongze Song. Documentation and tutorial data: CC BY 4.0.