From 326b01c85fbf473286d34c6702e3373f35c786ed Mon Sep 17 00:00:00 2001 From: Remi Gau Date: Fri, 6 Oct 2023 12:13:10 +0200 Subject: [PATCH] fix tables --- src/CHANGELOG.md | 10 ++++---- src/inputs.md | 52 ++++++++++++++++++++--------------------- src/outputs.md | 60 ++++++++++++++++++++++++------------------------ src/scope.md | 2 +- src/ui.md | 34 +++++++++++++-------------- 5 files changed, 79 insertions(+), 79 deletions(-) diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index 45f39c7..f47d630 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -28,11 +28,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Adopted Boutiques validatable and runnable descriptive standard -- Increased flexibility for runtime arguments and command-line formatting -- Defined exit codes to indicate various application outcomes -- Link between application descriptions and data specification versions -- Extensible definition which will scale with the BIDS standards as new entities are added +- Adopted Boutiques validatable and runnable descriptive standard +- Increased flexibility for runtime arguments and command-line formatting +- Defined exit codes to indicate various application outcomes +- Link between application descriptions and data specification versions +- Extensible definition which will scale with the BIDS standards as new entities are added ### Changed diff --git a/src/inputs.md b/src/inputs.md index d6beebd..8df0aab 100644 --- a/src/inputs.md +++ b/src/inputs.md @@ -8,31 +8,31 @@ fields, described fully in ## List of relevant inputs object properties for the BIDS Application specification -| Field name | Requirement Level | Data type | Description | -|:------------------|:--------------------|:------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| command-line-flag | OPTIONAL | String | For non-positional arguments, the flag which is associated with the argument on the command-line. | -| id | REQUIRED | String | The argument ID. Alphanumeric values and underscores only. CamelCase is recommended. | -| list | OPTIONAL | Boolean | Indicates whether or not the input field is a list of inputs. One of {true, false}. If omitted, it will be interpreted as false (for example non-list input). | -| name | REQUIRED | String | Plain text name of input for display. Can contain spaces. | -| optional | OPTIONAL | Boolean | Indicates whether or not the input field is required. One of {true, false}. If omitted, will be interpreted as false (for example non-optional input). | -| type | REQUIRED | String | One of {"String", "File", "Flag", "Number"}. | -| value-choices | OPTIONAL | List | List of possible values that the parameter may take. | -| value-key | OPTIONAL | String | String to replace in command-line template string. If specified, this MUST NOT be either a superset or subset of the value-key attribute associated with another object in the descriptor; to ensure this, brackets are typically used (for example "[value]"). | +| Field name | Requirement Level | Data type | Description | +|-------------------|-------------------|:----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| command-line-flag | OPTIONAL | String | For non-positional arguments, the flag which is associated with the argument on the command-line. | +| id | REQUIRED | String | The argument ID. Alphanumeric values and underscores only. CamelCase is recommended. | +| list | OPTIONAL | Boolean | Indicates whether or not the input field is a list of inputs. One of {true, false}. If omitted, it will be interpreted as false (for example non-list input). | +| name | REQUIRED | String | Plain text name of input for display. Can contain spaces. | +| optional | OPTIONAL | Boolean | Indicates whether or not the input field is required. One of {true, false}. If omitted, will be interpreted as false (for example non-optional input). | +| type | REQUIRED | String | One of {"String", "File", "Flag", "Number"}. | +| value-choices | OPTIONAL | List | List of possible values that the parameter may take. | +| value-key | OPTIONAL | String | String to replace in command-line template string. If specified, this MUST NOT be either a superset or subset of the value-key attribute associated with another object in the descriptor; to ensure this, brackets are typically used (for example "[value]"). | ### List of group object properties and their role within the BIDS Application specification In addition to describing inputs themselves, groups of inputs and their relationships can be defined as follows: -| Field name | Requirement Level | Data type | Description | -|:-------------------|:--------------------|:------------|:-------------------------------------------------------------------------------------------------| -| all-or-none | OPTIONAL | Boolean | True if all parameters included in this group need to be included together. . | -| description | RECOMMENDED | String | Description of the input group. | -| id | REQUIRED | String | A short, unique, informative identifier containing only alphanumeric characters and underscores. | -| members | REQUIRED | List | IDs of the input parameters belonging to this group. | -| mutually-exclusive | OPTIONAL | Boolean | True if only one input in the group may be selected at runtime. | -| name | REQUIRED | String | A human-readable name for the input group. | -| one-is-required | OPTIONAL | Boolean | True if at least one of the inputs in the group must be selected. | +| Field name | Requirement Level | Data type | Description | +|--------------------|-------------------|:----------|--------------------------------------------------------------------------------------------------| +| all-or-none | OPTIONAL | Boolean | True if all parameters included in this group need to be included together. . | +| description | RECOMMENDED | String | Description of the input group. | +| id | REQUIRED | String | A short, unique, informative identifier containing only alphanumeric characters and underscores. | +| members | REQUIRED | List | IDs of the input parameters belonging to this group. | +| mutually-exclusive | OPTIONAL | Boolean | True if only one input in the group may be selected at runtime. | +| name | REQUIRED | String | A human-readable name for the input group. | +| one-is-required | OPTIONAL | Boolean | True if at least one of the inputs in the group must be selected. | ## Required arguments @@ -43,13 +43,13 @@ be expressed in the tool's interface. ### List of custom object properties and roles within the BIDS Application specification. -| Argument ID | CLI Flag | Requirement Level | Data type | Description | -|:---------------|:---------------------|:--------------------|:------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| AnalysisLevel | `--analysis-level` | REQUIRED | String | String with value-choices which are a subset of {run, session, subject, dataset, meta}. The app may support one or more of these analysis levels. A default may be set, and unsupported analysis levels should return an exit code of 17, consistent with the definition in Table 7. | -| Help | `--help` | REQUIRED | Flag | Flag that specifies whether or not to show the help-text that describes how the tool may be correctly used. | -| InputDataset | `--input-dataset` | REQUIRED | List | List of URIs/paths of the BIDS datasets to be processed. Whether or not the order of listed datasets is important MUST be specified in the parameter description. The tool MUST NOT reorder the user-specified list. | -| OutputLocation | `--output-location` | REQUIRED | List | One URI/path to the location where all outputs will be stored. | -| ToolVersion | `--version` | REQUIRED | Flag | Returns the version of the tool being used. | +| Argument ID | CLI Flag | Requirement Level | Data type | Description | +|----------------|-------------------- |-------------------|:----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| AnalysisLevel | `--analysis-level` | REQUIRED | String | String with value-choices which are a subset of {run, session, subject, dataset, meta}. The app may support one or more of these analysis levels. A default may be set, and unsupported analysis levels should return an exit code of 17, consistent with the definition in Table 7. | +| Help | `--help` | REQUIRED | Flag | Flag that specifies whether or not to show the help-text that describes how the tool may be correctly used. | +| InputDataset | `--input-dataset` | REQUIRED | List | List of URIs/paths of the BIDS datasets to be processed. Whether or not the order of listed datasets is important MUST be specified in the parameter description. The tool MUST NOT reorder the user-specified list. | +| OutputLocation | `--output-location` | REQUIRED | List | One URI/path to the location where all outputs will be stored. | +| ToolVersion | `--version` | REQUIRED | Flag | Returns the version of the tool being used. | ## Backwards compatibility diff --git a/src/outputs.md b/src/outputs.md index 0bc4732..be63e88 100644 --- a/src/outputs.md +++ b/src/outputs.md @@ -10,18 +10,18 @@ datasets. ### List of relevant output-files object properties for the BIDS Application specification -| Field name | Requirement Level | Data type | Description | -|:----------------------------------|:--------------------|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| command-line-flag | OPTIONAL | String | Flag associated with the argument on the command-line. Examples: -o, --output | -| description | RECOMMENDED | String | A plain-text description of the output-files of the BIDS Application. | -| file-template | OPTIONAL | Array of strings | An array of strings that may contain value keys and together populate the self-contained structure of a configuration file. | -| id | REQUIRED | String | A short, unique, informative identifier containing only alphanumeric characters and underscores. Typically used to generate variable names. (should conform ^[0-9,_,a-z,A-Z]*$). Example: "data_file" | -| list | OPTIONAL | Boolean | True if output is a list of values. | -| name | REQUIRED | String | A human-readable output name. Example: 'Supplementary input file for X task'. | -| optional | OPTIONAL | Boolean | True if output may not be produced by the tool. | -| path-template | OPTIONAL | String | Describes the output file path relative to the execution directory. May contain input value keys and wildcards. Example: "xx". | -| path-template-stripped-extensions | OPTIONAL | List | List of file extensions that will be stripped from the input values before being substituted in the path template. Example: [". nii",". nii. gz"]. | -| value-key | OPTIONAL | String | A string contained in command-line, substituted by the output value and/or flag at runtime. | +| Field name | Requirement Level | Data type | Description | +|-----------------------------------|-------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| command-line-flag | OPTIONAL | String | Flag associated with the argument on the command-line. Examples: -o, --output | +| description | RECOMMENDED | String | A plain-text description of the output-files of the BIDS Application. | +| file-template | OPTIONAL | Array of strings | An array of strings that may contain value keys and together populate the self-contained structure of a configuration file. | +| id | REQUIRED | String | A short, unique, informative identifier containing only alphanumeric characters and underscores. Typically used to generate variable names. (should conform ^[0-9,_,a-z,A-Z]*$). Example: "data_file" | +| list | OPTIONAL | Boolean | True if output is a list of values. | +| name | REQUIRED | String | A human-readable output name. Example: 'Supplementary input file for X task'. | +| optional | OPTIONAL | Boolean | True if output may not be produced by the tool. | +| path-template | OPTIONAL | String | Describes the output file path relative to the execution directory. May contain input value keys and wildcards. Example: "xx". | +| path-template-stripped-extensions | OPTIONAL | List | List of file extensions that will be stripped from the input values before being substituted in the path template. Example: [". nii",". nii. gz"]. | +| value-key | OPTIONAL | String | A string contained in command-line, substituted by the output value and/or flag at runtime. | ## Execution Report & Updating Dataset Description When generated, an execution report that completely describes the processing @@ -83,21 +83,21 @@ POSIX and Windows environments: #### Reserved exit codes and their definitions -| Exit code | Definition | -|:------------|:--------------------------------------------------------------------------------------------| -| 0 | SUCCESS. The program completed successfully. | -| 1 | FAILURE. The program failed for unspecified reasons. | -| 2 | Reserved | -| 16-31 | BIDS-related codes. Reserved except the following | -| 16 | An input dataset failed BIDS validation. | -| 17 | Unknown analysis level. | -| 18 | Entity-based filtering options selected no files. | -| 19 | Both command-line arguments and a parameter invocation file were passed to the application. | -| 64-78 | BSD codes - Reserved except the following. | -| 64 | USAGE. The command was used incorrectly. | -| 65 | DATAERR. The input data was incorrect in some way. | -| 66 | NOINPUT. The input data was missing or unreadable. | -| 73 | CANTCREAT. An output file/directory cannot be created. | -| 74 | IOERR. Failure during file reading/writing. | -| 75 | TEMPFAIL. Temporary failure. Another run is expected to succeed. | -| 126-165 | BASH codes - Reserved | +| Exit code | Definition | +|:----------|---------------------------------------------------------------------------------------------| +| 0 | SUCCESS. The program completed successfully. | +| 1 | FAILURE. The program failed for unspecified reasons. | +| 2 | Reserved | +| 16-31 | BIDS-related codes. Reserved except the following | +| 16 | An input dataset failed BIDS validation. | +| 17 | Unknown analysis level. | +| 18 | Entity-based filtering options selected no files. | +| 19 | Both command-line arguments and a parameter invocation file were passed to the application. | +| 64-78 | BSD codes - Reserved except the following. | +| 64 | USAGE. The command was used incorrectly. | +| 65 | DATAERR. The input data was incorrect in some way. | +| 66 | NOINPUT. The input data was missing or unreadable. | +| 73 | CANTCREAT. An output file/directory cannot be created. | +| 74 | IOERR. Failure during file reading/writing. | +| 75 | TEMPFAIL. Temporary failure. Another run is expected to succeed. | +| 126-165 | BASH codes - Reserved | diff --git a/src/scope.md b/src/scope.md index 26bf523..9dc13a9 100644 --- a/src/scope.md +++ b/src/scope.md @@ -38,7 +38,7 @@ which were described in Gorgolewski, et al. 2017 (doi:[10.1371/journal.pcbi.1005209](https://doi.org/10.1371/journal.pcbi.1005209)), here referred to as BIDS-Apps 1.0. Backwards compatibility with BIDS-Apps 1.0 is not an explicit goal, but can be achieved in many cases as is discussed in -the section [on backwards-compatibility](./inputs#backwards-compatibility). A summary of changes from +the section [on backwards-compatibility](./inputs.md#backwards-compatibility). A summary of changes from BIDS-Apps 1.0 is included in the [CHANGELOG](./CHANGELOG.md#0.1.0.dev). This specification is seen as complementary to BIDS-Derivatives, which is part diff --git a/src/ui.md b/src/ui.md index c51306c..4942cbb 100644 --- a/src/ui.md +++ b/src/ui.md @@ -42,22 +42,22 @@ be simply named as name.json. ## List of relevant base Boutiques properties and their role within BIDS Applications. -| Field name | Requirement Level | Data type | Description | -|:--------------------|:--------------------|:------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| command-line | REQUIRED | String | A template string including the command and references to the value-keys of all possible inputs. The ordering imposed here may be significant, in particular for non-optional arguments. | -| custom | REQUIRED | Object | Object which can contain extensible metadata. This has a single required element, as described in Table 2. | -| inputs | REQUIRED | List | List of objects which contain input parameter definitions. Described in Table 3. | -| name | REQUIRED | String | The name of the BIDS Application. | -| output-files | REQUIRED | List | List of objects which contain output parameter definitions. Described in Table 6. | -| schema-version | REQUIRED | String | Boutiques schema version. Must be "≥0. 5". This is not to be confused with the BIDS Application schema and associated version. | -| tool-version | REQUIRED | String | Version of the BIDS Application. | -| description | RECOMMENDED | String | A plain-text description of the BIDS Application. | -| descriptor-url | RECOMMENDED | String | Link to the descriptor itself. Likely a GitHub repo alongside the described tool, for example. | -| doi | RECOMMENDED | String | DOI of the descriptor returned once published via Boutiques. (Note: This is not the DOI of the tool itself. ) | -| suggested-resources | RECOMMENDED | Object | Contains an execution walltime-estimate in seconds, memory usage in MB, and CPU/GPU usage in number of core threads/devices. | -| container-image | OPTIONAL | Object | The name and location of a container image, such as those in Docker or Singularity formats, containing the configured application. | -| error-codes | OPTIONAL | List | List of objects that contain error code information. The reserved error conditions are described in Table 7. | -| groups | OPTIONAL | List | List of objects that contain relational information among input parameters as described in Table 4. This is not to be confused with any other BIDS-relevant definition of groups. | +| Field name | Requirement Level | Data type | Description | +|---------------------|-------------------|:----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| command-line | REQUIRED | String | A template string including the command and references to the value-keys of all possible inputs. The ordering imposed here may be significant, in particular for non-optional arguments. | +| custom | REQUIRED | Object | Object which can contain extensible metadata. This has a single required element, as described in Table 2. | +| inputs | REQUIRED | List | List of objects which contain input parameter definitions. Described in Table 3. | +| name | REQUIRED | String | The name of the BIDS Application. | +| output-files | REQUIRED | List | List of objects which contain output parameter definitions. Described in Table 6. | +| schema-version | REQUIRED | String | Boutiques schema version. Must be "≥0. 5". This is not to be confused with the BIDS Application schema and associated version. | +| tool-version | REQUIRED | String | Version of the BIDS Application. | +| description | RECOMMENDED | String | A plain-text description of the BIDS Application. | +| descriptor-url | RECOMMENDED | String | Link to the descriptor itself. Likely a GitHub repo alongside the described tool, for example. | +| doi | RECOMMENDED | String | DOI of the descriptor returned once published via Boutiques. (Note: This is not the DOI of the tool itself. ) | +| suggested-resources | RECOMMENDED | Object | Contains an execution walltime-estimate in seconds, memory usage in MB, and CPU/GPU usage in number of core threads/devices. | +| container-image | OPTIONAL | Object | The name and location of a container image, such as those in Docker or Singularity formats, containing the configured application. | +| error-codes | OPTIONAL | List | List of objects that contain error code information. The reserved error conditions are described in Table 7. | +| groups | OPTIONAL | List | List of objects that contain relational information among input parameters as described in Table 4. This is not to be confused with any other BIDS-relevant definition of groups. | ### List of custom object properties and roles within the BIDS Application specification @@ -65,7 +65,7 @@ be simply named as name.json. The `custom` object has the following defined fields for use in the context of BIDS Applications. | Field name | Requirement Level | Data type | Description | -|:------------------------|:--------------------|:------------|:----------------------------------------------------------------------------------------------------------------------------------------| +|-------------------------|---------------------|-------------|-----------------------------------------------------------------------------------------------------------------------------------------| | BIDSAppSpecVersion | REQUIRED | String | The version of the BIDS application specification with which the application complies. | | OutputDataSpecification | OPTIONAL | List | If output data conforms to a standard definition (for example NIDM-1. 1. 0), these data standards may be included as a list of strings. | | | OPTIONAL | Any | Any key referring to arbitrary metadata that may be relevant or of interest to the application and its users. |