https://github.com/veupathdb/lib-jvm-blast
https://github.com/veupathdb/lib-jvm-blast
blast cli json kotlin library serialization
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/veupathdb/lib-jvm-blast
- Owner: VEuPathDB
- License: apache-2.0
- Created: 2021-04-28T13:11:31.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-11-09T16:04:31.000Z (over 2 years ago)
- Last Synced: 2025-08-06T09:50:42.406Z (11 months ago)
- Topics: blast, cli, json, kotlin, library, serialization
- Language: Kotlin
- Homepage:
- Size: 1.86 MB
- Stars: 0
- Watchers: 20
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.adoc
- License: license
Awesome Lists containing this project
README
= lib-jvm-blast
:source-highlighter: highlightjs
:toc: macro
image:https://img.shields.io/badge/docs-dokka-green[link="https://veupathdb.github.io/lib-jvm-blast/dokka/"]
image:https://img.shields.io/badge/docs-javadoc-blue[link="https://veupathdb.github.io/lib-jvm-blast/javadoc/"]
[WARNING]
====
This repository has been migrated into the link:https://github.com/VEuPathDB/service-multi-blast[MultiBlast Monorepo]
Maven packages will continue to be published to this repository as per GitHub's
rules, however all future code updates will be published to the MultiBlast
Monorepo.
====
toc::[]
Library for parsing, serializing, and validating JSON BLAST+ cli configs.
Configs may be constructed or parsed from JSON and written out to several
formats including a CLI call string.
Supports ncbi/blast 2.11.0, 2.12.0, and 2.13.0
Requires Java 16+.
== Usage
.Building a CLI Command
[source, kotlin]
----
val config = Blast.blastn()
config.task = BlastNTaskType.DiscontiguousMegablast
config.queryFile = "my-query.txt"
config.dbFile = "my-blast-db"
config.toCliString() == "blastn -task 'dc-megablast' -query 'my-query.txt' -db 'my-blast-db'"
----
.Serializing to JSON
[source, kotlin]
----
val config = Blast.blastp()
config.task = BlastPTaskType.BlastPFast
config.queryFile = "my-query.txt"
config.dbFile = "my-blast-db"
config.toJson() == """
{
"tool" : "blastp",
"-task" : "blastp-fast",
"-query" : "my-query.txt"
"-db" : "my-blast-db"
}
"""
----
.Deserializing from JSON
[source, kotlin]
----
val inputJson = """
{
"tool" : "blastx",
"-task" : "blastx-fast"
"-query" : "my-query.txt"
"-db" : "my-blast-db"
}
"""
val config = Blast.blastx(inputJson) // or Blast.of(inputJson) if the tool is unknown.
assert(config.task == BlastXTaskType.BlastXFast)
assert(config.queryFile == "my-query.txt")
assert(config.dbFile == "my-blast-db")
----
== Default Values
This library knows all the documented default values for all flags for each
BLAST+ tool, and will omit those values from serialized forms. This is done to
keep the serialized form of each config down to the bare minimum as the BLAST+
tools have a large number of flags and options.
.Setting Default Values
[source, kotlin]
----
val config = Blast.deltablast()
config.seg = SegDelta.no()
config.gapTrigger = 22.0
config.compBasedStats = CompBasedStatsDeltaValue.CompBasedStats
config.toCliString() == "deltablast"
config.toJson() == """
{
"tool" : "deltablast"
}
"""
----
== Validation
=== Field Level Validation
Each field that has a documented set or range of valid values validates the set
value on construction, preventing an invalid flag being used when building a
BLAST+ tool configuration.
If an invalid value is used when constructing a field, an
`IllegalArgumentException` will be thrown.
[source, kotlin]
----
val field = LineLength(-1) // Throws an exception
----
=== Config Level Validation
In addition to the field level validation, whole configs come with a `validate`
method that builds a list of errors for flags that are incompatible with one
another or require an additional flag that is missing.
This validation method returns a `Map` of all the errors encountered keyed on
the name of the relevant flag.
[source, kotlin]
----
val config = Blast.blastFormatter()
config.archive = "some-archive"
config.rid = "some-request-id"
val errors = config.validate()
errors.toJson() == """
{
"-archive" : [ "Incompatible with -rid" ],
"-rid" : [ "Incompatible with -archive" ]
}
"""
----