Getting started with ecoClassify

Here we provide a guided tutorial on ecoClassify, an open-source package for developing and applying an image classifier model.

ecoClassify is a package for SyncroSim, yet familiarity with SyncroSim is not required to get started with ecoClassify. Throughout the Quickstart tutorial, terminology associated with SyncroSim is italicized, and whenever possible, links are provided to the SyncroSim online documentation. For more on SyncroSim, please refer to the SyncroSim Overview and Quickstart tutorial.


ecoClassify Quickstart Tutorial

This quickstart tutorial will introduce you to the basics of working with ecoClassify. The steps include:

  1. Installing ecoClassify
  2. Opening a configured ecoClassify library
  3. Viewing model inputs
  4. Running models
  5. Viewing model outputs and results


Step 1: Installing ecoClassify

EcoClassify is a package within the SyncroSim modeling framework and requires SyncroSim Studio to be installed on your computer. Download the latest stable release of SyncroSim Studio here and follow the installation prompts.

Open SyncroSim Studio and select File > Local Packages. This will open the Local Packages window in the main panel of SyncroSim Studio. In the bottom left corner, click on Install from Server…, select ecoClassify from the window that opens, and click OK.

If you do not have Miniconda installed on your computer, a dialog box will open asking if you would like to install Miniconda. Click Yes. Once Miniconda is done installing, a dialog box will open asking if you would like to create a new conda environment. Click Yes. Note that the process of installing Miniconda and the ecoClassify conda environment can take several minutes. If you choose not to install the conda environment you will need to manually install all required package dependencies.

Miniconda is an installer for conda, a package environment manager that installs any required packages and their dependencies. By default, ecoClassify runs conda to install, create, save, and load the required environment for running ecoClassify. The ecoClassify environment includes R and Python software and associated packages.


Step 2: Opening a configured ecoClassify library

Having installed the ecoClassify package, you are now ready to create your SyncroSim library. A library is a file (with extension .ssim) that contains all your model inputs and outputs. Note that the layout of each library is specific to the package for which it was initially created. You can opt to create an empty library or download the ecoClassify template library, called Snow Classifier (Jumpingpound Mountain, Alberta). In this tutorial, we will be working with the Snow Classifier (Jumpingpound Mountain, Alberta) library, which we will download from SyncroSim Cloud.

Navigate to SyncroSim Cloud and click on the Explore tab in the top right menu. This will take you to the list of Public Libraries available for anyone to download, open, and run in SyncroSim Studio. Scroll through the list of libraries, or begin typing Snow Classifier (Jumpingpound Mountain, Alberta) in the search bar to find the pre-configured ecoClassify library. Click on the library to open it on the cloud.


Download the library by clicking on the Download library button in the top right corner. This downloads a backup file of the library, which is denoted by the file extension .ssimbak, and contains the library file as well as accompanying data.


In SyncroSim Studio, open the example library by selecting File > Open. Navigate to where the .ssimbak file was saved (the default is your Downloads folder), select it, and click Open. In the new File Explorer window that opens, navigate to the folder where you would like to save the extracted library – here we save the library to our C:\Temp\ folder. Click Save.

The ecoClassify example library was created with SyncroSim Studio v3.0.9. If you have a more recent release of SyncroSim Studio installed, you will automatically be prompted to update the library to configure it to your installed version of the software. Click Apply.


Step 3: Viewing model inputs

The contents of your newly opened library are now displayed in the Library Explorer. The library stores information on three levels: the library, the project, and the scenarios.

Most model inputs in SyncroSim Studio are organized into scenarios, where each scenario consists of a suite of properties, one for each of the model’s required inputs. Because you downloaded and opened a complete ecoClassify library, your library already contains two demonstration scenarios with pre-configured model inputs and outputs. For the purpose of this tutorial’ we’ll focus on the Snow Classifer [Random Forest] scenario.


To view the details of the scenario:

This opens the scenario properties window.


Pipeline

Located underneath the General tab, the model Pipeline allows you to select which stages of the model to include and in what order they should be run. A full run of ecoClassify consists of two stages:

Note that the Forecast stage is dependent on the results of the previous stage, Train Classifier. You cannot run a stage without having first run the previous required stages.


Next, click on the Datafeeds node. Here, all of the inputs to the model are listed as individual datasheets. Notice how some rows have a green checkmark in the Data column to indicate these datasheets contain data. From here, you can navigate to these individual datasheets by clicking on their name in the View column, or by navigating to the next tab called Image Classifier.


Input

The first node under the Image Classifier tab is the Input node. Expand this node to reveal the following input datasheets:

The Classifier options datasheet is where you may specify a sample size, choose whether you would like to apply contextualization or not, and choose from a drop-down menu of model types. Model types currently available include Random Forest and MaxEnt.In this example scenario, we use a Random Forest model.


Post-processing options is where you can choose to apply filtering or not. If you choose to apply filtering, you may also apply a filter resolution and threshold.


Finally, the Input rasters datasheet is where all spatial data are loaded into the library. This includes training and ground-thruth rasters for creating the classifier, as well as the rasters that you would like to apply the classifier to. Note that this datasheet also contains a Timestep column. In the ecoClassify package, timesteps are used to link training rasters with their corresponding ground truth raster, and to distinguish these rasters from those that will be classified.


Step 4: Running models

Right-click on the Snow Classifer [Random Forest] in the Library Explorer window and select Run from the context menu. If prompted to save your project, click Yes. The example model run should complete within a couple of minutes. If the run is successful, you will see a Status of Done in the Run Monitor window. If the run fails, you can click on the Run Log link to see a report of any problems that occurred.


Step 5: Viewing model outputs and results

Once the run is complete, you can view the details of the result scenario:



You can look through the result scenario to see the updated or newly populated datasheets. You should find that the Output datasheet, Statistics, has been populated with model run outputs.


Model Outputs

To view spatial outputs, move to the results panel at the bottom left of the Library Explorer window. Under the Maps tab, double-click on the Predicted Presence [Classified] map to visualize the classified rasters.


The first two columns show the Unfiltered and Filtered classified rasters compared to the Probability maps of snow presence.


Next, double-click on the Predicted Presence [Training] map to view the Unfiltered and Filtered results of the training rasters compared to the Probability and Ground Truth maps of snow presence and absence.


ecoClassify also allows you to visual the RGB images of your classified and training rasters under the Images tab.


Here, you may also view a confusion matrix quantifying the classifier’s performance and a bar chart of the classifier’s variable importance. In this Random Forest example, we can see that the SR_B2 variable was the most important variable in training the model.


Export Data

To export a map or model output created by the ecoClassify package, add the result scenario with the desired outputs to the results and open the Export tab at the bottom of the screen. All available files for export will be listed. To export, simply double-click on the desired output and choose the directory in which to save the file in the pop-up window. Note that if multiple result scenarios are included in the active result scenarios, files for each of the selected scenarios will be exported.