Using translators

Using translator plugins

What are translators?

A translator is an approach to reading BEL Nanopubs from, and writing BEL Nanopubs to, a file format. They are modeled as plugins to allow users to support their own formats when necessary (Plugins in bel.rb). For example you may find it useful to encode BEL Nanopubs in a TAB-separated file for spreadsheet manipulation. Read Creating a translator plugin to learn how to create your own translator plugin.

A translator provides the following capabilities:

read

Read converts input, encoded in the represented file format, to a stream of BEL Nanopub objects.

write

Write converts a stream of BEL Nanopub objects to output that is encoded in the represented file format.

Here is a visualization of the process using the TAB-separated file format described above:

How are translators accessed?

command

A translator can be accessed using the bel translate command. This command allows the translation of one BEL Nanopub format into another. For example to convert our TAB-separated file to BEL Script we can execute:

bel translate -i "nanopubs.tsv" tsv bel
# translate the "nanopubs.tsv" file from tsv to bel

Here tsv identifies the TAB-separated format and bel identifies the BEL Script format.

For help documentation run:

bel translate --help

ruby

A translator can be accessed within ruby. Not surprisingly the bel translate command uses the below ruby methods to carry out its job.

require 'bel'

# retrieve BEL Script translator
bel_script_translator = BEL.translator(:bel)

# read a stream of BEL Nanopubs from a BEL Script file
bel_nanopubs_from_bel_script = bel_script.read(
  File.open('full_abstract1.bel', 'r')
).each

# retrieve XBEL translator
xbel_translator = BEL.translator(:xbel)

# write a stream of BEL Nanopubs to an XBEL file
xbel_translator.write(
  bel_nanopubs_from_bel_script,
  File.open('full_abstract1.xbel', 'w')
)

This translate process can be shortened to:

require 'bel'
BEL.translate(
  File.open('full_abstract1.bel', 'r'),
  :bel,
  :xbel,
  File.open('full_abstract1.xbel', 'w')
)

How are translators identified?

Translators can be identified by an id, file extension, or media type. These values are assigned by the author of the translator plugin.

Returning to our TAB-separated file format, mentioned in What are translators?, we identify the translator plugin by the following:

• Identifier
  • tsv
• File extension
  • tsv
• Media type
  • text/tab-separated-values

We can use any of these identifiers to refer to the TAB-separated translator:

bel translate -i "nanopubs.tsv" \
  text/tab-separated-values application/xml

How do I know which translators are available?

You can list all plugins known to the bel.rb library with:

bel plugins --list

You will see the available translators under the Translator plugins header.