The aim of this community is to collect the code and code documentation produced by the Centre of Excellence for Climate Extremes (CLEX). CLEX is a major initiative funded by the Australian Research Council (ARC). This Centre of Excellence is an international research consortium of five Australian universities and a network of outstanding national and international partner organisations.

Click on 'read more' to know how to use and contribute to this collection, use clexcodecollection<at>gmail.com to contact us

CLEX Code Collection policies and guidelines

Table of contents

1. Guidance for end users
2. Guidance for contributors
3. Authorship Policy
4. Retention and retraction policy

 

Guidance for end  users

 

Who can use

Anyone! All records available on the CLEX Code Collection are required to have an open access license.

 

How to use

If you have found a record in the CLEX Code Collection that you would like to use, please read the record description and download the code from the source. Where applicable, check that you have access to any required datasets and installed relevant software packages before executing the code.

We request that any published research stemming from a record within the CLEX Code Collection appropriately cite the source as provided in the record description.

 

How to get help

The codes have not been tested by the curators of the collection. For basic troubleshooting the curation team encourages end users to email the main contact provided in the record.

In instances where you found a scientific error in the code and the author is not responding within a fortnight, please contact the curation team at: clexcodecollection<at>gmail.com.

For further clarification on how issues are resolved please consult the issues workflow. 

 

Asking follow-up questions

Remember that authors are not required to answer all queries about their code, and therefore responses may not be immediate. Prior to contacting authors, it is recommended that end users search possible solutions on platforms like Stack Overflow. If you have not found an answer to your problem and need to contact the author directly, check if your question falls within the type of questions authors have indicated they will support in the record description and/or the source webpage of the record where applicable. 

Finally, check guidelines on how to ask a good question from Stack Overflow and ResearchGate. As a general rule, the clearer and more precise your question is, the better an answer you will receive. 

 

Disclaimer

While the curation team endeavours to maintain the usability and scientific validity of all records that are part of the CLEX Code Collection, we accept no liability for the damages arising from the use of the codes.

The curation team will regularly maintain the collection and update the title and description of records in instances where there are scientific errors as per the procedures described in the Retention and Retraction Policy.

It is the end user's responsibility to check whether the code is suitable for their intended use and if there are updates to the record on the CLEX Code Collection that they are using.

 

Guidance for software contributors

 

Who can submit entries

The curation team accepts “any code” contribution from CLEX researchers, students and collaborators which is relevant to climate science.

All authors must comply with all applicable laws and not be intentionally malicious. Codes should adhere to the Authorship Policy and not violate any prior license agreement. 

Should the code contain or require any sensitive data, the authors must comply with the disclosure conditions of any prior ethics agreement.

Authors are encouraged to record their code under version control software before contribution (eg. on Github, Bitbucket, Gitlab). Preferably, the authors should then create their own record on Zenodo under their own account (an ORCID can be used to create a Zenodo account). Zenodo can connect with, for example, Github for easy creation of the record from the information on a Github repository. Only the owner of the original Zenodo record is allowed to amend the record.

 

Required description expected from contributors

All code submissions will require a description that is adequate for an end user unfamiliar with the code to download, compile and run. Therefore, mandatory content includes:

• Brief description of:

  • the purpose and scope

  • Software requirements (where applicable)

  • Data requirements (where applicable) - particularly if any intermediate data processing is required before using the tool

  • An example of how to execute the code

  • Ideally authors should also include information on what level of support they are willing to provide to end users. This may include bug reporting, improvements, documentation updates and repurposing code for other datasets.

• Valid contact details for end users and the curation team to ask follow-up questions. These contact details should be kept up-to-date.

• Ideally the authors should also provide their ORCID for tracking citations of the contribution

• Keywords for searchability. We provide a minimum keyword requirements list.

• License agreement

A code can have several authors. All authors should have made a significant contribution to the code. A person is not an author if their contribution only constitutes of:

• supervision

• the provision of funding, data, materials, infrastructure or access to equipment

• the provision of routine technical support, technical advice or technical assistance

• providing feedback or a review of the code

 

We created a step-by-step guide  and a checklist to show how to upload a record.

 

Review Process

All submissions will be reviewed to ensure documentation requirements are met. A workflow on the review process is available.

Once all requirements have been met, the curator will either link the existing Zenodo record to the CLEX Code Collection or create a new Zenodo record.
 

Follow-up Questions

Authors to the CLEX Code Collection agree to be contactable by the curating team and end users whenever issues or bugs are detected. Ideally, authors should respond to queries in a timely manner. We detailed how issues will be dealt with in this workflow.

Issues that impact the scientific validity of the code will have a warning flag added to the Zenodo record to ensure that end users are aware. Ideally these should be resolved within six months of identification. If the issue remains unresolved the record will be retracted from the CLEX Code Collection only, and not on the host repository. Refer to the Retraction policy for more information.

Authors are encouraged, but are not required to answer questions that end users may have regarding their code. Authors must keep their contact details up to date in the Zenodo record. Authors must provide their preferred contact method for queries about the code, which may include an email address or persistent researcher ID (e.g., ORCID) or link to a repository in another platform (e.g., Github).

Authors must also specify if they are able/willing to provide limited (e.g., bug reporting) or full assistance (e.g., adapting software/scripts to a different field than was initially intended).

 

Procedures for updates 

Authors may choose to further amend the code on the host repository. For published records, code changes will require a new version to be recorded in Zenodo. The contribution will be reviewed again. In some exceptional cases, the author might be required to create an entire new record. The curators of the CLEX Code Collection will guide the authors on the process if this exception applies

If there are frequent end user queries on how to get the code to work, the curator will seek an amendment of the record description from the author.

Should end users make amendments to the code, they are encouraged to collaborate with the authors.

 

Authorship policy

 

You can only submit a code for which you are an author. 

An author is a person who has created or modified a code in a substantial way, either as an individual or part of a group effort. 

A code can have several co-authors. All co-authors should have made a significant contribution to the code. Each author needs to give their agreement to be listed as an author. In addition, if some co-authors are not from CLEX, they should give their agreement for the code to be listed under the CLEX Code Collection.

It is possible to define contributors in the CLEX Code Collection, some of the potential contributor roles are:

• Reviewer 

  • To qualify, the review needs to be a substantial effort, which results in improvements/changes being applied to the code. 

• Curator 

  • Person tasked with reviewing, enhancing, cleaning, or standardizing the code and the associated metadata in a way that goes beyond the ordinary curation of the code collection

• Content-expert 

  • Someone who contributed mainly by providing advice/review on the scientific validity of the code

These definitions are based on the authorship and co-authorship policy on the Australian Code for the Responsible Conduct of Research 2018.

You can only submit a modified code if the modifications add value to the code. For example, the new code may improve efficiency or the ease of use or include scientific changes.

When submitting a modified code, the authors are responsible to ensure the licensing and ethical terms of the original code allow for that submission. 

Examples of code where you are an author and therefore may submit the code to the CLEX Code Collection:

1. You created a new analysis code based on widely used modules/packages/libraries of the software language of your code. 

2. You modified someone else’s analysis code:

   • By rewriting a code to a different language (e.g from matlab to Python)

   • By updating an old code to a new version of the software language or software packages requiring significant changes

   • By adding extra analysis steps and complexity

   • By updating an existing code to run on a new set of data that requires additional steps to process the same analysis.

 

Examples of code where you are not an author and therefore do not meet requirements as a new record in the CLEX Code Collection: 

 

1. Changes only affecting paths to the data. E.g. to use a code on a different server or with a different set of data. 

2. Changes to underlying packages that require to change only a few function arguments.

 

Retention and retraction policy

 

CLEX will actively maintain the Code Collection and retain your records for its lifetime (end of 2024). After that CLEX cannot guarantee that the curation of the Collection will continue. The Code Collection will continue to exist on Zenodo and the records will be retained provided they do not violate the Zenodo policies. The retention time for Zenodo is the lifetime of their host laboratory CERN, currently funded for the next 20 years. For more information or updates check the Zenodo policies page.

 

Record removal

• Records will be immediately removed, if the curator finds they are in breach of the authorship policies.

• Records will be removed should scientific errors in the code be raised and no reasonable attempt is made on the owner's side to review and amend the issues. The procedure and timeframe for this are described in the Amendment procedure section below.

 

Obsolete records

• If the software/package versions are outdated and no longer supported and the code cannot be executed without revision, the contact author will be advised and opportunities provided to update the code to more recent software versions. If this cannot be done, code will be marked as obsolete.

 

Amendment procedure

In case of significant scientific errors:

• The Collection curator will warn the contact author and establish a course of action to amend the erroneous code.

• The curator will then put a warning on the record stating the nature of the issue and the potential timeframe for resolution.

• If the record is amended, a new version will be published and the older one retained for provenance reasons. The title of the erroneous version will be altered to notify clearly that it is retracted, and a summary of the issue and its resolution will also be added to the description.

• If no amendment/correction is made, the record will be removed from the collection. Note that any retraction will only remove the record from the collection and not the original source (e.g. that may be on github, bitbucket, the author’s own Zenodo account etc.)

• Where the curation team has ownership of the original Zenodo code, we will alter the title and description to reflect the retraction state.

 

In case of obsolete code:

• The Collection curator will warn the contact author and establish a course of action to update the code.

• The curator will then put a warning on the record stating that the code is deemed obsolete and the reasons for this. 

• If the author agrees to updating the code, the warning should also display the likely timeframe of the update. If the record is amended, then a new version will be published and any warning on previous versions removed

• If the author decides not to update the code, it will be marked as obsolete. A notice explaining why the code is deemed obsolete and the reasons it will not be updated will be added to the description.