If your model has failed and you don’t know why, this is a quick general checklist that can help you verify whether you have designed the experiment correctly. 

1. Check the requirements for the data format (CSVs, Tiffs) that the EcoCommons platform accepts
2. Check that all climate environmental layers and occurrence records are properly selected and listed under your selected ‘Study Area’ region
3. Tree-based models typically require more data than other methods - make sure you have enough records to run this type of model
4. Random seed – sometimes the pseudo-absence points generated cannot be used to train a viable model and it will fail. Setting a new random seed can help with this. If users are finding that only certain random seeds are working for a model, this could indicate that model viability is more dependent on pseudo-absence over occurrence point distributions.
5. Check the log file (.Rout) which you can find under: Failed experiment > model result files > ‘Log file’(.Rout) > View > Scroll to the bottom to find out where the model has stopped executing.

1. If there are no outputs check for the error messages  

Follow these steps to locate the error message:-

Open the failed experiment and click ‘View job information’.

The first field under ‘Details’ will give the error message 

The error message will look like this:

Note: If the model is still failing consistently, please contact our support team at ‘support@ecocommons.org.au’. It helps us immensely to have the Log files or Error message. You can also share the experiment with the Support account (support@ecocommons.org.au). Our team will go through the model and investigate the issues further.

There are a number of things that may cause an experiment to fail. Sometimes your whole experiment might fail, other times it might be one single algorithm within your experiment. Below we have listed the most common scenarios for failed experiments and how to fix them: 

Your entire experiment has failed

If you get this first message then something went wrong with either the design of your experiment, the data that you have selected, or an error occurred with sending your experiment to the compute resources. Issues with connecting to the compute happen relatively rarely but we have experienced them occasionally. 

The fix: 

• To check whether your experiment failed because the Modelling Wizard failed to connect to the computing resources, please resubmit your experiment. You can do this by going back to the main 'Experiments' tab and clicking on the 'Rerun' button next to your experiment. Therefore, you will be asked to revisit your experiment setup and check whether all entered information is correct.
• If your experiment fails again, then it is mostly that there is an issue with the experimental design or dataset you are using – please refer to the troubleshooting list provided on the following page.

One or more algorithm/s within your experiment failed 

Example:

Sometimes, more than one algorithms within an experiment can fail at the same time. Each model algorithm has different requirements which you can learn more about within our individual algorithm support articles here. 

We have outlined the most common reasons for this below. If you think that your model failed for another reason, please get in contact.

Species Distribution Model & Multi-Species Distribution Model experiment fail

Script execution failed with exit code 256

These are the most common error messages you can receive, and unfortunately, they can mean a number of things. The most common of these are outlined below:

1. You are running a Maxent model with your own uploaded environmental data which has non-square cells.
   If you are using your own environmental data, and Maxent failed, please check the Log File in the results. If you scroll all the way down, you are likely to see the following message: "Error in .startAsciiWriting(x, filename, ...):   x has unequal horizontal and vertical resolutions. Such data cannot be stored in arc-ascii format". This means that your environmental data is stored in non-square cells rasters, which is not supported by Maxent within the R package dismo which the EcoCommons platform uses. Please consider resampling your environmental rasters on a square grid.
   
    
2. You used categorical data in an algorithm that does not accept categorical data. Algorithms like Bioclim or Surface Range Envelope  cannot use categorical variables. These algorithms will fail if you try to run them with categorical data layer.
   
   
    
3. The number of species occurrence records is too low.
   While some algorithms are able to handle a low number of occurrence records (e.g. <20), others are not. Machine learning algorithms (e.g. Classification Tree) require a larger occurrence dataset due to the iterative process in which the algorithm uses the data. If you are modelling a rare or threatened species and only have a small occurrence dataset, we advise using Maxent or a statistical algorithm (e.g. Generalized Linear Model) to calibrate your data.
   
   
    
4. The species names in your occurrence .CSV are numeric.
   If your species or multi-species occurrence file has numbers for species name/s (e.g. 1, 2, 3) the model will fail to generate a valid formula for the model and the experiment will fail. To fix this, you need to modify your occurrence data file and use non-numeric values for all species names (e.g. A, B, C instead of 1, 2, 3). Once you have done this, re-upload this dataset into the platform and try running your SDMs/MSDMs again with this new file.
   
   
    
5. "Failed to transfer results back"
   This is an issue with the compute and the connections. Rerun your experiment and it should fix this issue.
   
   
    
6. You only selected one variable in your model.
   With the exception of and other geographic models, all SDM algorithms will fail if you only include one predictor variable in the experimental design. Rerun your experiment and ensure you include at least 2 predictor variables.
   
   
    
7. Circles failed for a widespread species.
   The Circles algorithm draws a circle of a given radius around your occurrence records. By default, this radius is computed from the mean of all distances between the species location points. This can be a really large distance, for example if you are modelling a marine species that occurs across the globe. In this case some circles might overlap, and the algorithm tries to merge these circles which might result in a failed experiment. The solution is to rerun the experiment with a fixed distance for the radius.

1. The environmental data you uploaded includes spaces or special characters in the name.

When you upload your own environmental data for a species distribution model experiment the variable names (column headers) should not include spaces or special characters as the data may not be read in correctly and the experiment will fail.

Species Trait Modelling experiment fails

1. There are spaces in the species trait names if data is uploaded as our own.

When you upload data for a species trait model experiment the trait names (column headers) should not include spaces as the data may not be read in correctly and the experiment will fail.

1. Whether one of the column configurations is set as a fixed factor.

When you design your species trait model experiment, under ‘Configuration’ tab it is required to nominate at least one column with the trait values and one column to be set as fixed factor from the imported or uploaded ‘Input data’. For specific cases, you need to indicate whether your trait data are continuous, nominal (categorical data with no order, such as color) or ordinal (categorical data with an order, such as cover: low-medium-high).

NB. If your dataset contains multiple species you can run:

• An analysis based on species level trait data (average trait values per species) by making sure the Species column is set to Ignore (or used as a random factor in GLMM).
• An analysis per species based on individual trait measurements by selecting a Species column. This will run each analysis on each species separately.

Climate Change Projection experiment fails

1. You ran your SDM with more than one current climate dataset.
   When you use the results of an SDM experiment in a Climate Projection, the projection tries to match the variables from your SDM with the selected future climate dataset. However, if you have duplicate layers from different datasets (e.g. Worldclim bioclim variables 1 - 19, and Climond bioclim variables 1 - 19) the model does not know which to use, and therefore it fails. We recommend rerunning your SDM with only one of your chosen datasets (e.g. Worldclim OR Climond, but not both), and then run your Climate Projection using that new SDM. We also advise to use future climate data from the same data collection as the current climate data (e.g. if you use Worldclim current climate in your SDM experiment then you should also use the Worldclim future data for your projection) to ensure that the data were generated using the same methodology.

1. You used a future climate dataset that has different layers compared to the SDM.
   The Climate Change Projection uses the relationship modelled between presence/absence and environmental conditions from the SDM and only substitutes the values of the predictor variables used in the SDM with new values predicted for the future. Therefore, the layers in the climate data selected in the Climate Change Projection experiment need to match the layers used in the SDM. For example, your experiment will fail if you used long-term climate data in the SDM, and select monthly future data in the Climate Change experiment, or if you used marine data in the SDM and select terrestrial data in the Climate Change experiment or vice versa.

1. You used your own uploaded future climate data.
   If you uploaded your own future climate data, you need to make sure that the layers have the same names as the layers used in your SDM. The projection will only substitute the values of predictor variables used in the SDM with new values for future predictions. To match these layer names, you need to edit your future climate data. Please read this article for instructions.

We hope that these instructions were useful to you to find solutions to failed experiments.