Merge pull request #79 from ResearchObject/rq4

Reference environment files using buildInstructions

Author: stain

docs/profiles/0.5-DRAFT/provenance_run_crate/index.md

@@ -469,6 +469,59 @@ In some workflow systems (e.g., CWL, Galaxy), tools are typically wrappers for a
 }
 ```
 
+## Tool runtime environment 
+
+While the `softwareRequirements` of a tool can [specify software dependencies](../process_run_crate#specifying-software-dependencies) (as above) in terms of naming software, a more reproducible definition of a tool's runtime environment may need to include a particular set of binaries that are compiled and/or distributed to work together. (Note that _runtime environment_ here refers to a set of software, configuration and other dependency files, not [environment variables](../workflow_run_crate#environment-variables-as-formal-parameters)).
+
+Some workflow engines support such package systems as a way to distribute tool dependencies, typically by referring to an _environment file_ which can be programmatically instantiated to retrieve and install a given set of binaries. In a Provenance Crate, environment files are indicated as `buildInstructions` for either the `HowToStep` (for a given step) or the `HowTo` (for the whole workflow).
+
+For instance, to indicate a [Conda environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) for a Nextflow workflow:
+
+```json
+{
+    "@id": "main.nf",
+    "@type": ["File", "SoftwareSourceCode", "ComputationalWorkflow", "HowTo"],
+    "name": "Hello world in Nextflow",
+    "programmingLanguage": {
+        "@id": "https://w3id.org/workflowhub/workflow-ro-crate#nextflow"
+    },
+    "buildInstructions": {
+        "@id": "environment.yml"
+    }
+},
+{ 
+    "@id": "environment.yml",
+    "@type": "File",
+    "name": "Conda environment",
+    "encodingFormat": "application/yaml", 
+    "conformsTo": { 
+        "@id": "https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually",
+    }
+},
+{ 
+    "@id": "https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually",
+    "@type": "WebPageElement",
+    "name": "Conda environment file"
+}
+```
+
+
+The `encodingFormat` and/or contextual identifier for `conformsTo` SHOULD be provided for machine-readable build/dependency environment files, but it is currently out of scope for this profile to list all possible package environment systems.
+
+The term `buildInstructions` is taken from [CodeMeta terms](https://codemeta.github.io/terms/), which are [scheduled to be included](https://github.com/ResearchObject/ro-crate/pull/276) in the RO-Crate 1.2 JSON-LD context. For RO-Crate 1.1, the term must be added to the `@context` as:
+
+```json
+{
+    "@context": [
+        "https://w3id.org/ro/crate/1.1/context",
+        "https://w3id.org/ro/terms/workflow-run",
+        { "buildInstructions": "https://codemeta.github.io/terms/buildInstructions" }
+    ],
+    "@graph": [...]
+}
+```
+
+
 
 ## Conditional step execution
 

docs/profiles/0.5-DRAFT/provenance_run_crate/ro-crate-metadata.json

@@ -46,7 +46,8 @@
         { "@id": "https://w3id.org/ro/terms/workflow-run#ParameterConnection" },
         { "@id": "https://w3id.org/ro/terms/workflow-run#connection" },
         { "@id": "https://w3id.org/ro/terms/workflow-run#sourceParameter" },
-        { "@id": "https://w3id.org/ro/terms/workflow-run#targetParameter" }
+        { "@id": "https://w3id.org/ro/terms/workflow-run#targetParameter" },
+        { "@id": "https://codemeta.github.io/terms/buildInstructions" }
     ],
     "hasResource": [
         { "@id": "#hasSpecification" },
@@ -385,6 +386,21 @@
     "inDefinedTermSet": { "@id": "https://w3id.org/ro/terms/workflow-run#" },
     "description": "The target (upstream) parameter"
   },
+  {
+    "@id": "https://codemeta.github.io/terms/buildInstructions",
+    "@type": "DefinedTerm",
+    "name": "buildInstructions",
+    "termCode": "buildInstructions",
+    "description": "Build environment file (e.g. for Conda)",
+    "inDefinedTermSet": { "@id": "https://codemeta.github.io/terms/" }
+  }, 
+  {
+    "@id": "https://codemeta.github.io/terms/",
+    "@type": "DefinedTermSet",
+    "name": "Codemeta Terms",
+    "url": "https://codemeta.github.io/terms/",
+    "version": "3.0"
+  },
   {
     "@id": "https://pypi.org/project/runcrate/",
     "@type": "SoftwareApplication",

docs/profiles/0.5-DRAFT/provenance_run_crate/ro-crate-preview.html

@@ -88,6 +88,9 @@
         },
         {
           "@id": "https://w3id.org/ro/terms/workflow-run#targetParameter"
+        },
+        {
+          "@id": "https://codemeta.github.io/terms/buildInstructions"
         }
       ],
       "hasResource": [
@@ -426,6 +429,16 @@
       },
       "description": "The target (upstream) parameter"
     },
+    {
+      "@id": "https://codemeta.github.io/terms/buildInstructions",
+      "@type": "DefinedTerm",
+      "name": "buildInstructions",
+      "termCode": "buildInstructions",
+      "description": "Build environment file (e.g. for Conda)",
+      "inDefinedTermSet": {
+        "@id": "https://codemeta.github.io/terms/"
+      }
+    },
     {
       "@id": "#hasSpecification",
       "@type": "ResourceDescriptor",
@@ -841,6 +854,13 @@
       "@type": "Person",
       "name": "Salvador Capella-Gutierrez"
     },
+    {
+      "@id": "https://codemeta.github.io/terms/",
+      "@type": "DefinedTermSet",
+      "name": "Codemeta Terms",
+      "url": "https://codemeta.github.io/terms/",
+      "version": "3.0"
+    },
     {
       "@id": "http://schema.org/MediaObject",
       "@type": "DefinedTerm",
@@ -970,6 +990,8 @@ <h3><a href="https://w3id.org/ro/wfrun/provenance/0.5-DRAFT">Go to: </a> Provena
                         <li><a href="#https%3A//w3id.org/ro/terms/workflow-run%23sourceParameter">source parameter</a></li>
 
                         <li><a href="#https%3A//w3id.org/ro/terms/workflow-run%23targetParameter">target parameter</a></li>
+                        
+                        <li><a href="#https%3A//codemeta.github.io/terms/buildInstructions">buildInstructions</a></li>
                         </ul></td>
             </tr><tr>
             <th style="text-align:left;" class="prop">hasResource<span>&nbsp;</span><a href="http://www.w3.org/ns/dx/prof/hasResource">[?]</a></th>
@@ -1678,6 +1700,42 @@ <h3><a href="https://w3id.org/ro/terms/workflow-run#targetParameter">Go to: </a>
             </table>
         </div>
 
+        </div>
+        <hr/><br/><br/>
+           <div>
+            <h3><a href="https://codemeta.github.io/terms/buildInstructions">Go to: </a> buildInstructions</h3>
+            
+            
+            
+            
+        <div id="https://codemeta.github.io/terms/buildInstructions">
+            
+            <table class="table metadata table-striped" >
+                <tbody><tr>
+            <th style="text-align:left;" class="prop">@id</th>
+            <td style='text-align:left'><a href="https://codemeta.github.io/terms/buildInstructions">https://codemeta.github.io/terms/buildInstructions</a></td>
+            </tr><tr>
+            <th style="text-align:left;" class="prop">name<span>&nbsp;</span><a href="http://schema.org/name">[?]</a></th>
+            <td style='text-align:left'><span>buildInstructions</span></td>
+            </tr><tr>
+            <th style="text-align:left;" class="prop">@type</th>
+            <td style='text-align:left'><span>DefinedTerm</span></td>
+            </tr><tr>
+            <th style="text-align:left;" class="prop">description<span>&nbsp;</span><a href="http://schema.org/description">[?]</a></th>
+            <td style='text-align:left'><span>Build environment file (e.g. for Conda)</span></td>
+            </tr><tr>
+            <th style="text-align:left;" class="prop">termCode<span>&nbsp;</span><a href="http://schema.org/termCode">[?]</a></th>
+            <td style='text-align:left'><span>buildInstructions</span></td>
+            </tr><tr>
+            <th style="text-align:left;" class="prop">inDefinedTermSet<span>&nbsp;</span><a href="http://schema.org/inDefinedTermSet">[?]</a></th>
+            <td style='text-align:left'><a href="#https%3A//codemeta.github.io/terms/">Codemeta Terms</a></td>
+            </tr><tr><th colspan="2" style="text-align:center">Items that reference this one</th><tr><tr>
+            <th style="text-align:left;" class="prop">hasPart<span>&nbsp;</span><a href="http://schema.org/hasPart">[?]</a></th>
+            <td style='text-align:left'><a href="#https%3A//w3id.org/ro/wfrun/provenance/0.5-DRAFT">Provenance Run Crate profile</a></td>
+            </tr></tbody>
+            </table>
+        </div>
+
         </div>
         <hr/><br/><br/>
            <div>