search

make-models-fair / coordination

Coordinating efforts for Making Models FAIR
0 stars 1 forks source link

guimera-etal-2005 #5

Open kaclaborn opened 1 year ago

kaclaborn commented 1 year ago

This is the first comment in the issue associated with the following model publication:

Guimerà , R., Uzzi, B., Spiro, J., & Nunes Amaral, L.A. (2005). Team assembly mechanisms determine collaboration network structure and team performance. Science, 308(5722), 697-702.

Working Repository: https://github.com/make-models-fair/guimera-etal-2005

Use this issue for:

Be sure to update the issue with a green label, indicating the appropriate model category. Also, make sure that you stay up to date with the yellow labels, indicating the model's status in the making FAIR process.

Mohsen-Shahbaznezhadfard commented 1 year ago

In the comment thread below, the experiences, challenges, and how to face them in the process of making the Guimera et al. (2005) model FAIR are explained:

Availability of the code - Is it clean and commented?: At the beginning of the work, it was searched on the Internet using the keywords of the title of the article (Team assembly mechanisms determine collaboration network structure and team performance), whether a clue of the code related to the model of this article can be found there or not. After this process, a code called "Team Assembly" which is on the NetLogo platform was found in the NetLogo library. In two parts of the model info related to the found code, it is stated that "It is an adaptation of the team assembly model presented by Guimera, Uzzi, Spiro & Amaral (2005)" and "This model is based on: R Guimera, B Uzzi , J Spiro, L Amaral. Team Assembly Mechanisms Determine Collaboration Network Structure and Team Performance. Science 2005". Although at first glance, based on the keywords "adaptation" and "based on", one may guess that this code is exactly the code related to the model of this article, but it should be noted that such keywords or similar words may sometimes be misleading (the found code might be an incomplete state or an extended or modified state of the original model code of the article in question). For this purpose, to ensure that the found code is an exact replication of the Guimera et al. (2005) article model, the parameters and how they affect and function in the found code and the explanations provided in the article were examined and compared. It was also tried to compare the results presented in the article and the results related to performing similar initial analyzes in the found code. Based on this, it was ensured that the found code, which is sufficiently cleaned up and commented, is an exact replication of the article model.

Mohsen-Shahbaznezhadfard commented 1 year ago

Checking the model code license: The next step was to check the model code license. Based on what is mentioned in the code model info that is available in the NetLogo library, this work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 License. Based on this license and the investigations that were done, the license remained the same in the continuation of the work process.

Mohsen-Shahbaznezhadfard commented 1 year ago

Creating the model documentation: After going through the process explained in the previous comments, it was time to write and set the model documentation. In this step, first by scrutinizing the code, the model info of this code that is available in the NetLogo library, and the explanations provided in the article about the stages of model development, a general text describing the purpose, functionality and process flow of the code was written, and also some notes were taken from the most important parts of them. Then an attempt was made to convert these writings and notes into the ODD protocol format which provides a standardized and comprehensive way to describe agent-based models and facilitates understanding, comparison, and replication of models.

Mohsen-Shahbaznezhadfard commented 1 year ago

Archiving the model code on GitHub: The next step was to archive the model code in a repository on GitHub. At this stage, all relevant files including code, documentation, and license were archived in a template repository on GitHub, the link of which is available through tobefair.org. It should be noted that at this stage the documentation file, which was originally a Word file, was added to the repository as a reStructuredText file (.rst). Because .rst files are lightweight, easy to version control, and can be easily converted into various formats, including HTML and PDF. Also, the full text of the license was found in the form of a PDF file on its website. However, for better accessibility, after converting its format, it was added to the repository as a plain text file (.txt).

Mohsen-Shahbaznezhadfard commented 1 year ago

Assigning a DOI to the model code repository: At this stage, it was time to assign a DOI to the model code repository. It should be noted that since the CoMSES archiving platform did not have the option of our code license (this may cause challenges of incompatibility between licenses), and also because of the archive of this code on GitHub, the Zenodo option was considered for assigning a DOI. Finally, a separate file containing the assigned DOI was added to the repository.

Mohsen-Shahbaznezhadfard commented 1 year ago

Learning from the process: From a learning perspective, involvement in this project provided significant opportunities to improve skills, practices, and protocols for making computational models FAIR. Specifically, it could help to acquire practical skills in working with Git/GitHub, a powerful tool for efficient and collaborative version control of code, enabling teams to track changes, work together seamlessly, and deploy projects more easily.