Blog
Nov 20 2023
New Integrations and Tools - Fall 2023
Article de blogue en français ici
Borealis upgraded to Dataverse version 5.13 earlier this year (see previous blog post). The Borealis team has been configuring additional new features that bring support for:
To test these features, feel free to use our demo sandbox environment. Please reach out if you have any questions or feedback.
Github integration: Upload to Borealis using a GitHub Action
What is it?
GitHub repository content can be uploaded to an existing Borealis dataset using a “GitHub Action” called the Dataverse Uploader Action.
What is the use-case?
This integration provides a simplified way to backup your GitHub repository to a Borealis dataset. This customizable action can allow you to:
- Upload the entire GitHub repository or specific subdirectories
- Automatically synchronize at trigger events (e.g., push, release) or manually using the workflow dispatch event
- Turn on/off deleting dataset content before uploading from GitHub
- Turn on/off automatically publishing a new version of the dataset
How do I access this feature?
- Within your GitHub repository, create a YML file (i.e., workflow.yml) file within the directory called .github.workflows/ (see screenshot below)
- Enter your configurations, such as the trigger events (shown below in top box, lines 1 to 3), and whether you would like to upload the entire repository (default) or specific subdirectories.
- Add your API token as a secret variable (shown below in bottom box, line 12)
- Input the server URL (e.g., https://borealisdata.ca, https://demo.borealisdata.ca) and dataset DOI (e.g., doi:xx.xxxx/xxx/xxxxxx) (shown below in bottom box, lines 13 and 14)
After the GitHub action uploads the files to Borealis, you will see the files show up in the file list with file-level metadata “Uploaded with GitHub Action from” with the name of your repository appended (see screenshot below).
ZIP previewer and option to download a single file within a zip
What is it?
ZIP archives can now be previewed within the browser and individual files can be selected for download.
What is the use-case?
Originally users needed to download an entire ZIP archive in order to view the files inside, even if they only needed a subset of the files. This new previewer allows users to review the files prior to download and only download a subset as needed.
How do I access this feature?
- Navigate to a ZIP archive and click on the preview icon (see screenshot).
2. After accepting any access terms of use, you will be able to view the structure of the ZIP archive, navigate the file hierarchy, and download individual files (see screenshot below).
NcML and ELN (NcML) previewer
What is it?
With the latest upgrade, the Dataverse software now detects NetCDF and HDF5 files based on their content and attempts to extract metadata in NcML (XML) format and save as an auxiliary files. Additionally, ELN files are also detected.
We’ve now configured previewers to allow users to preview NcML files and ELN files. For more information, see our previous blog post and the Advanced Guide.
What is the use-case?
NetCDF (Network Common Data Form) is a machine independent data format, an international standard of the Open Geospatial Consortium, and commonly used in environmental and climate sciences.
HDF5 (Hierarchical Data Format) is an open source file format that supports large and complex data.
The ELN file format was developed to improve interoperability among different ELN software. This archive format allows for the import/export of research data, such as experimental results, protocols, descriptions, templates, etc.
These previewers allow users to explore these files before downloading.
How do I access this feature?
Navigate to the file list for files that have been detected as NetCDF, HDF5, or ELN. Click on the eye icon to access the previewer.
Once the previewer opens, users will be able to view the contents of the file with the NetCDF previewer.
Computational Workflow Metadata Block
What is it?
A computational workflow describes a process to coordinate multiple computational tasks and their data dependencies that lead to the resulting finalized dataset, for example: running code, using command-line tools, accessing a database, submitting a job to a compute cloud resource, and execution of data processing scripts. In the diagram below, an example workflow is shown where the original data follows a series of tasks and conditions that are mapped out as steps, ultimately resulting in the final data product.
(Source: Institute for Quantitative Social Science. (accessed 2023-06-01). Dataverse User Guide https://guides.dataverse.org/en/5.13/user/dataset-management.html#computational-workflow)
Computational workflow information can be included within Borealis in two ways. First, users can apply a “workflow” tag to computational workflow files that are uploaded to Borealis. Second, Borealis now has a computational metadata workflow metadata block that can link to an external code repository where the related code and workflow steps are stored. These two options are described further below.
What is the use-case?
Including computational workflows as part of dataset documentation is increasingly becoming part of best practices to support transparent data management and reproducibility. Computational workflow information helps future dataset users better understand how the original data are transformed into the finished product.
How do I access this feature?
There are two options for including computational workflow information within Borealis:
- Create a computational workflow file using a framework or tool (e.g., Common Workflow Language (CWL), R Notebook, workflow registries). Then, upload your file to your dataset and add a custom tag called “workflow” (see screenshot below).
(Source: Institute for Quantitative Social Science. (accessed 2023-06-01). Dataverse User Guide https://guides.dataverse.org/en/5.13/user/dataset-management.html#computational-workflow)
(Source: Institute for Quantitative Social Science. (accessed 2023-06-01). Dataverse User Guide https://guides.dataverse.org/en/5.13/user/dataset-management.html#computational-workflow)
2. Once the dataset is saved, go to the “Metadata” tab and select “Add + Edit Metadata.” Navigate to the computational workflow metadata block and add details to link to external code repositories that contain the code and related details about computational workflow steps. The fields can contain details about the type of computational workflow framework, the external code repository URL where the related code is located, and the URL to documentation or text describing the Computational Workflow and its use.
For more information:
Goble et al., (2020) FAIR Computational Workflows. https://direct.mit.edu/dint/article/2/1-2/108/10003/FAIR-Computational-Workflows
Dataverse Guides. “Dataset + File Management.” https://guides.dataverse.org/en/5.13/user/dataset-management.html#computational-workflow
Nov 20 2023
Nouvelles intégrations et outils - Automne 2023
Borealis est passé à la version 5.13 du logiciel Dataverse plus tôt cette année (voir l’article de blogue précédent). L’équipe de Borealis a configuré les nouvelles fonctionnalités qui prennent en charge :
Pour tester ces fonctionnalités, n’hésitez pas à utiliser la plateforme de démonstration. Contactez-nous pour toute question ou tout commentaire.
L’intégration GitHub - téléversement vers Borealis à l’aide d’une action GitHub
Qu’est-ce que c’est?
Le contenu du dépôt GitHub peut être téléversé dans un ensemble de données Borealis existant à l’aide d’une « action GitHub » appelée Action de téléchargement de Dataverse.
Quel est le cas d’utilisation?
Cette intégration offre un moyen simplifié de sauvegarder votre dépôt GitHub dans un ensemble de données Borealis. Cette action personnalisable permet :
- le téléversement de l’intégralité du dépôt GitHub ou des sous-répertoires spécifiques
- la synchronisation automatique lors d’évènements déclencheurs (p. ex., pousser, libérer) ou manuelle à l’aide de l’évènement de répartition du flux de travail
- l’activation/désactivation de la suppression du contenu de l’ensemble de données avant de le téléverser depuis GitHub
- l’activation/désactivation de la publication automatique d’une nouvelle version de l’ensemble de données
Comment accéder à cette fonctionnalité?
- Dans le dépôt GitHub, créez un fichier YML (c’est-à-dire workflow.yml) fichier dans le répertoire appelé .github.workflows/ (voir capture d’écran ci-dessous)
- Saisissez vos configurations, telles que les évènements déclencheurs (voir l’encadré du haut, lignes 1 à 3), et si vous souhaitez téléverser l’intégralité du dépôt (par défaut) ou des sous-répertoires spécifiques
- Ajoutez votre jeton API comme variable secrète (voir l’encadré du bas, ligne 12)
- Entrez l’URL du serveur (p. ex., https://borealisdata.ca/fr, https://demo.borealisdata.ca/fr) et l’ensemble de données DOI (p. ex., doi:xx.xxxx/xxx/xxxxxx) (voir l’encadré du bas, lignes 13 et 14)
Capture d’écran du fichier YML d’un dépôt GitHub avec l’action définie pour être libérée et manuellement et le jeton API inclus comme variable secrète.
Une fois que l’action GitHub a téléversé les fichiers dans Borealis, vous verrez les fichiers apparaître dans la liste des fichiers avec les métadonnées de fichier « Téléchargé avec l’action GitHub depuis » avec le nom de votre dépôt (voir capture d’écran ci-dessous).
Aperçu ZIP et la possibilité de télécharger un seul fichier dans une archive ZIP
Qu’est-ce que c’est?
Il est maintenant possible d’obtenir un aperçu des archives ZIP dans le navigateur et les fichiers individuels peuvent être sélectionnés pour le téléchargement.
Quel est le cas d’utilisation?
À l’origine, les gens devaient télécharger une archive ZIP entière afin de visualiser les fichiers qu’elle contenait, même si seul un sous-ensemble de fichiers était requis. L’outil d’aperçu permet de consulter les fichiers avant de les télécharger et de télécharger uniquement un sous-ensemble au besoin.
Comment accéder à cette fonctionnalité?
- Accédez à une archive ZIP et cliquez sur l’icône Aperçu (voir capture d’écran).
2. Après avoir accepté les conditions d’utilisation d’accès, vous pourrez visualiser la structure de l’archive ZIP, naviguer dans la hiérarchie des fichiers et télécharger des fichiers individuels (voir capture d’écran ci-dessous).
Aperçu NcML et ELN (NcML)
Qu’est-ce que c’est?
Depuis la dernière mise à niveau, le logiciel Dataverse détecte désormais les fichiers NetCDF et HDF5 en fonction de leur contenu et tente d’extraire les métadonnées au format NcML (XML) et de les enregistrer comme fichiers auxiliaires. De plus, les fichiers ELN sont également détectés.
Nous avons maintenant configuré l’aperçu pour vous permettre d’obtenir un aperçu des fichiers NcML et ELN.
Pour plus d’information, consultez notre article de blogue précédent (https://spotdocs.scholarsportal.info/pages/viewpage.action?pageId=305397835#Mise%C3%A0niveaudeBorealisverslaversion5.13-Soutienpourlad%C3%A9tectiondefichiersNetCDFetHDF5) et le Guide avancé (https://guides.dataverse.org/en/latest/user/dataset-management.html#netcdf-and-hdf5) (en anglais).
Quel est le cas d’utilisation?
NetCDF (Network Common Data Form) est un format de données indépendant de la machine, une norme internationale de l’Open Geospatial Consortium et couramment utilisé dans les sciences de l’environnement et du climat.
HDF5 (Hierarchical Data Format) est un format de fichier libre qui prend en charge des données volumineuses et complexes.
Le format de fichier ELN a été développé pour améliorer l’interopérabilité entre les différents logiciels ELN. Ce format d’archive permet l’importation/exportation de données de recherche, telles que des résultats expérimentaux, des protocoles, des descriptions, des modèles, etc.
L’aperçu vous permet d’explorer ces fichiers avant de les télécharger.
Comment accéder à cette fonctionnalité?
Accédez à la liste des fichiers pour les fichiers détectés comme NetCDF, HDF5 ou ELN. Cliquez sur l’icône en forme d’œil pour accéder à l’aperçu.
Lorsque l’outil d’aperçu s’ouvre, vous pourrez visualiser le contenu du fichier grâce à l’aperçu NetCDF.
Métadonnées du flux de travail informatique
Qu’est-ce que c’est?
Un flux de travail informatique décrit un processus permettant de coordonner plusieurs tâches de calcul et leurs dépendances de données qui conduisent à l’ensemble de données finalisé résultant, p. ex., l’exécution de code, l’utilisation d’outils de ligne de commande, l’accès à une base de données, la soumission d’une tâche à une ressource de calcul en infonuagique et l’exécution de scripts de traitement de données. Dans le diagramme ci-dessous, un exemple de flux de travail est présenté dans lequel les données d’origine suivent une série de tâches et de conditions qui sont organisées en étapes, aboutissant finalement au produit de données final.
(Source : Institute for Qualitative Science (consulté le 01/06/2023). Guide d’utilisation de Dataverse https://guides.dataverse.org/en/5.13/user/dataset-management.html#computational-workflow)
L’information sur le flux de travail informatique peut être incluse dans Borealis de deux manières. Premièrement, les utilisateurs peuvent appliquer une balise « flux de travail » aux fichiers de flux de travail informatique téléversés dans Borealis. Deuxièmement, Borealis dispose désormais d’un bloc de métadonnées de flux de travail informatique qui peut être lié à un dépôt de code externe où sont stockés le code et les étapes associées. Ces deux options sont décrites plus en détail ci-dessous.
Quel est le cas d’utilisation?
L’inclusion de flux de travail informatiques dans la documentation des ensembles de données fait de plus en plus partie des meilleures pratiques pour soutenir la gestion transparente et la reproductibilité des données. L’information permet une meilleure compréhension de la transformation des données d’origine en produit fini lors d’utilisations futures de l’ensemble de données.
Comment accéder à cette fonctionnalité?
Il existe deux options pour inclure l’information sur le flux de travail informatique dans Borealis :
- Créer un fichier de flux de travail informatique en utilisant un cadre ou un outil (p. ex., Common Workflow Language (CWL), Carnet R, registres de flux de travail). Ensuite, téléversez le fichier dans l’ensemble de données et ajoutez une balise personnalisée appelée « flux de travail » (voir capture d’écran ci-dessous).
2. Une fois l’ensemble de données enregistré, accédez à l’onglet « Métadonnées » et sélectionnez « Ajouter + Modifier les métadonnées ». Accédez au bloc de métadonnées du flux de travail informatique et ajoutez des détails en pour lier les dépôts de code externes contenant le code et les détails associés sur les étapes du flux de travail informatique. Les champs peuvent contenir des détails sur le type de structure de flux de travail informatique, l’URL du dépôt de code externe où se trouve le code associé et l’URL de la documentation ou du texte décrivant le flux de travail informatique et son utilisation.
Pour plus d’information :
Goble et al., (2020) Flux de travail informatiques FAIR. https://direct.mit.edu/dint/article/2/1-2/108/10003/FAIR-Computational-Workflows
Guides de Dataverse. « Ensemble de données + gestion de fichiers. » https://guides.dataverse.org/en/5.13/user/dataset-management.html#computational-workflow