2  How to Use It

To get started using LogoClim, you must have NetLogo installed. The model was developed with NetLogo 7.0.4. Use this version or newer for best compatibility. The NetLogo website provides easy installers for Windows, macOS, and Linux, along with detailed instructions for installation.

The model also depends on the NetLogo extensions: GIS, Pathdir, String, and Time. These extensions are installed automatically when the model is run for the first time.

With NetLogo ready, follow these steps to get LogoClim up and running.

2.1 Steps

2.1.1 A. Download the Model

You can download the latest release of the model from the CoMSES Network. This is the recommended option for most users, as it provides a stable version of the model that has been tested and documented.

For the development version, you can clone or download the model GitHub code repository directly.

2.1.2 B. Prepare the Data

The CoMSES Network release includes an example dataset that is ready to use with LogoClim. You can use it as a starting point. But, ideally you should prepare your own data to suit your research needs. The user manual will guide you through the process of downloading and preparing WorldClim data for use with LogoClim.

We also provide other example datasets for testing and demonstration. These files are available in the model’s OSF repository and are ready to use with LogoClim. Please note that these datasets are for demonstration purposes only and are not suitable for research applications. Always verify the suitability of the data for your specific research questions and objectives.

2.1.3 C. Run the Model

With the files at hand, open the logoclim.nlogox file in NetLogo. You can find this file in the code directory when using the CoMSES Network release or in the nlogox folder when using the development version.

Use the Select Data Directory button in the model interface to specify their location. This will set the data-path global variable to the correct path, allowing the model to access the data. After that, you can configure the other parameters as needed.

Once everything is set, click on the Setup and then Go buttons to start the simulation.

Figure 2.1: Future Climate Data series at 2.5-minute resolution (~21 km2 at the equator), displaying the Total Precipitation (mm) variable for India in December 2081–2100 under the SSP-585 scenario, as estimated by the CMCC-ESM2 global climate model. Click on the image to enlarge it.

2.2 Interface

Here is a brief overview of the model interface and its controls.

2.2.1 Buttons

  • Setup: Initializes the simulation with the selected parameters.
  • Go: Starts or resumes the simulation.
  • Go Back: Steps the simulation backward in time. This also reset ticks and clear all the plots.
  • Go Forward: Steps the simulation forward in time.
  • Select Data Directory: Opens a dialog window, allowing the user to indicate the data directory.
  • Show Values: Displays patch values when hovering the mouse over them.

2.2.2 Choosers, Input Boxes, Sliders, and Switches

  • data-series (string): Chooser for selecting a data series (e.g., "Future Climate Data").
  • data-resolution (string): Chooser for selecting the spatial resolution of the data, expressed in minutes of a degree of latitude/longitude (e.g., "5 Minutes (~85 km2 at the Equator)").
  • climate-variable (string): Chooser for selecting the climate variable (e.g., "Average Temperature (°C)").
  • bioclimatic-variable (string): Chooser for selecting a bioclimatic variable (e.g., "BIO18 - Precipitation of Warmest Quarter"). Only useful when climate-variable is set to bioclimatic-variables.
  • global-climate-model (string): Chooser for selecting a global climate model (e.g., "ACCESS-CM2"). Only useful when Future Climate Data is selected.
  • shared-socioeconomic-pathway (string): Chooser for selecting a Shared Socioeconomic Pathway (SSP) scenario (e.g., "SSP-370"). Only useful when Future Climate Data is selected.
  • start-month (string): Chooser for selecting the simulation’s starting month (e.g., "April").
  • start-year (number): Input box for setting the simulation’s start year in YYYY format (e.g. 1970).
  • data-path (string): Input box for setting the path to the data folder. Use the Select Data Directory button to navigate via a dialog window.
  • historical-climate-color (number): Input box for setting the color used to represent the Historical Climate Data series.
  • historical-monthly-weather-color (number): Input box for setting the color used to represent the Historical Monthly Weather Data series.
  • future-climate-color (number): Input box for setting the color used to represent the Future Climate Data series.
  • background-color (number): Input box for setting the color used for the background of the world map.
  • color-bar-bins (number): Slider for setting the number of bins in the Color Bar plot.
  • black-value (number): Slider for setting the lower threshold on the world map.
  • black-min (boolean): Switch for setting the black color threshold to the minimum value of the current dataset. If it is set to On, black-value will be ignored.
  • white-value (number): Slider for setting the upper threshold on the world map.
  • white-max (boolean): Switch for setting the white color threshold to the maximum value of the current dataset. If it is set to On, white-value will be ignored.

2.2.3 Monitors and Plots

  • Climate Variable: Displays the climate variable being used. If climate-variable is set to Bioclimatic Variables, it instead shows the variable selected in the bioclimatic-variable chooser.
  • Month, Year: Displays the current month and year being simulated.
  • Color Bar: A plot showing the color scale used on the world map, with black representing the lowest value and white representing the highest value. The color scale is divided into bins, which can be adjusted using the color-bar-bins slider.
  • Mean, Standard Deviation, Minimum, Maximum: Monitors and plots showing the minimum, maximum, mean, and standard deviation values for the climate variable across the patches. If more than 12 months of data are available, a line matching the series color marks the start of each 12-month cycle, and a 12-month moving average (12MA) is added to highlight trends.

2.2.4 Color Scale

LogoClim uses a color scale ranging from black (representing the lowest value) to white (representing the highest value). Users can adjust the thresholds for these colors using the black-value and white-value sliders. Alternatively, users can set the black or white color to automatically represent the minimum or maximum value of the current data by toggling the black-min and white-max switches.

2.3 Integrating with Other Models

LogoClim was created to be integrated with other models using NetLogo’s LevelSpace extension. This extension enables parallel execution and data exchange between models. The following chapters of this manual provide guidance on how to integrate LogoClim with other model.

To facilitate this integration, we created the Logônia model (Vartanian et al., 2026), a fictional plant-growth model providing a practical example of how to integrate LogoClim. It is also available on the CoMSES Network and its code repository is available on GitHub.

Figure 2.2: Logônia interface. Click on the image to enlarge it.