2.16. ベストプラクティス#
以下は、ツールやワークフローのCWL定義を書く際に留意すべき推奨グッドプラクティスのセットです。これらのガイドラインは、有用性の尺度で検討するために提示されています:多ければ多いほど良いが、すべてが必要なわけではありません。
入力または参照のファイルやディレクトリの名前に
type: string
を使用しません。type:File
またはtype: Direcotry
を適宜使用します。CWL 定義(
Dockerfile
のような外部コンポーネントと合わせて)は、ソフトウェアコードです。ワークフロー開発者は、ソフトウェアライセンスに関する通常の規則がこのCWL定義に適用されることを認識する必要があります。例えば、ワークフローが一般に共有される場合、将来のユーザーがどのような条件でワークフローを実行、修正、および/または他のワークフローと組み合わせることができるかを理解するために、ライセンス条項は明確でなければなりません。このような理由から、CWL定義にライセンスフィールドを含めることを検討してください。このガイドの著者は、独自のライセンスを作成するのではなく、既存のライセンスを選択することをお勧めします(ライセンスの選択について詳しくは、以下のリンクを参照してください)。そして、私たちの推奨する実践は、誰でも再利用できるライセンスを選択することです。例えば Apache 2.0です。可能であれば、ライセンスは対応する SPDX 識別子 と共に指定されるべきです。
https://spdx.org/licenses/[SPDX-ID]
(SPDX-ID
は、上記のリンク先の識別子のリストから選択) という形式の URL を指定して、ライセンスのメタデータフィールドを構築します。以下の例を参照してください。SPDX識別子のない非標準ライセンスの場合は、そのライセンスへのURLを指定します。参考文献:"A Quick Guide to Software Licensing for the Scientist-Programmer"
SPDX 識別子を持つライセンスのメタデータフィールドの例:
$namespaces: s: https://schema.org/ s:license: https://spdx.org/licenses/Apache-2.0 # other s: declarations
CWL定義にメタデータを与える例については、 このユーザーガイドのメタデータと著者名のセクションを参照してください。
ツール定義では、
SoftwareRequirement
.の下に、短い名前を使用して依存関係をリストアップします。https://identifiers.org/rrid/RRID:SCR_NNNNNN
形式で依存関係のための SciCrunch 識別子を書きます。input
およびoutput
の識別子はすべて、その概念的同一性を反映する必要があります。foo_input
,foo_file
,result
,input
,output
, などの代わりにunaligned_sequences
,reference_genome
,phylogeny
, またはaligned_sequences
などの情報量の多い名称を使ってください。ツール定義では、
SoftwareRequirement
の下に、このツール定義で動作することが確認されているツールのバージョンのリストを書きます。format
は、すべての入力および出力File
に指定する必要があります。バイオインフォマティクスツールは、EDAMのフォーマット識別子を使用するのが良いです。iana:text/plain
,iana:text/tab-separated-values
、$namespaces:{ iana: "https://www.iana.org/assignments/media-types/" }
も参照してください`.IANA メディアタイプ一覧(MIME タイプとしても知られています)。バイオインフォマティクス以外のツールについては、同様に適切なオントロジー/統制語彙を使用または構築してください。このページを編集して私たちに知らせてください。File
の入出力のうち、ストリーミング互換の方法(一度だけ利用されて、ランダムアクセスなし、訳注標準入出力のイメージ)で読み書きされるものを、streamable: true
としてマークします。各
CommandLineTool
の定義は、たとえ(サブ)コマンドがそれ以上の機能を備えていたとしても、一つの使用方法のみに焦点を当てるべきです。必要ないまたは、使用しないオプションでツールの定義を複雑にし過ぎないようにしましょう。カスタム型は、型定義ごとに1つの外部YAMLで定義すると再利用しやすくなります。
ツール/ワークフローを要約したトップレベルの短い
label
を含めます。有用であれば、トップレベル
doc
も含めてください。これは、トップレベルlabel
(上記参照)で提供されたものより長く詳細な説明を記述します。有効な値のリストが決まっている要素には、
type: string
の代わりに、type: enum
を使用してください。JavaScriptのすべての使用について、削除または置換の可能性を評価します。よくある例:
File
の名前とパスを操作する方法は?basename
,nameroot
,nameext
, などの ビルトインFile
プロパティ のいずれかを代わりに使用できないか考えてみてください。ツール定義を同僚(できれば別の機関の人)に渡し、テストしてもらい、フィードバックをもらいましょう。
抽象化できる個々のコンポーネントを持つ複雑なワークフローは、ワークフローをモジュール化し、その一部を容易に再利用できるようにするために、
SubworkflowFeatureRequirement
を利用します。ソフトウェアのコンテナは、"Recommendations for packaging and containerizing of bioinformatics software" に準拠するようにします(他の分野でも有用です)。