lszeremeta/sdfeater repository overview

SDF⁠ parser written in Java is run from the command-line interface (CLI). You don't need to have new Java installed! Java 8 and above are supported. Do you love️ Docker? You can use a lightweight SDFEater container⁠! SDFEater not only eats parses your SDF files, but also can add additional data to the output. The choice of output formats is really wide.

⁠Quick start

Use SDFEater in 3 easy steps. In this example, we will use the ChEBI⁠ dataset and ready to use JAR file. You need Java 8+ installed.

1. Download the ready-to-use JAR SDFEater-VERSION-jar-with-dependencies.jar file from project release⁠ asset.

SDFEater is also available as a Docker image⁠. In most scenarios, JAR file or the Docker image should be sufficient and convenient to run SDFEater, but you may want to build everything yourself⁠.

1. Download ChEBI complete 3-star dataset file⁠ and unpack downloaded gz archive. ChEBI datasets are shared via FTP, so if your browser or operating system does not support FTP, you may need an additional program such as FileZilla⁠.
2. Assuming the ChEBI_complete_3star.sdf file is in the current directory and the output format you're interested in is RDFa, the command will be as follows:

    java -jar SDFEater-VERSION-jar-with-dependencies.jar -f rdfa -i ChEBI_complete_3star.sdf > ChEBI_complete_3star_rdfa.html

That's all. Now you have the RDFa file ready in the current directory. You can try other output formats and options as described below. You can also use SDFEater to convert DrugBank SDF files⁠ or prepare your own SDF input file with supported keys⁠.

⁠Docker image

If you have Docker⁠ installed, you can use a tiny SDFEater Docker image from Docker Hub⁠.

Because the tool is closed inside the container, you have to mount⁠ a local directory with your input file. The default working directory of the image is /app. You need to mount your local directory inside it (e.g. /app/input):

docker run --rm --name sdfeater-app --mount type=bind,source=/home/user/input,target=/app/input,readonly lszeremeta/sdfeater:latest

In this case, the local directory /home/user/input has been mounted under /app/input.

You can also simply mount the current working directory using $(pwd) sub-command:

docker run --rm --name sdfeater-app --mount type=bind,source="$(pwd)",target=/app/input,readonly lszeremeta/sdfeater:latest

⁠CLI options

Running SDFEater without parameters displays help.

• -i,--input <arg> - input SDF file path (required)
• -f,--format <arg> - output format (e.g. cypher, jsonld, cvme, smiles, inchi) (required; full list below)
• -s,--subject <arg> - subject type (iri, uuid, bnode; iri by default; for all formats excluding cypher, cvme, smiles, inchi)
• -b,--base <arg> - molecule subject base for 'iri' subject type ('https://example.com/molecule#entity⁠' by default)

Remember about the appropriate file path when using the Docker image. Suppose you mounted your local directory /home/user/input under /app/input and the path to the SDF file you want to use in SDFEater is /home/user/input/file.sdf. In this case, enter the path /app/input/file.sdf or input/file.sdf as the value of the -i argument.

⁠Output formats

You can specify the output format using -f,--format. Available output formats:

• cypher - Cypher⁠ molecule, atoms, bonds and relation ready to import to the Neo4j graph database⁠,
• cypheru - the same as cypher option, but try to generate full database URLs instead of IDs,
• cypherp - the same as cypher option, but add additional atoms data from periodic table⁠,
• cypherup - the same as cypher option, but added URLs and additional atoms data from periodic table⁠,
• cvme - CVME⁠ file format based on SKOS,
• smiles - plain text SMILES (if available in the molecule property)
• inchi - plain text InChI (if available in the molecule property)
• turtle - Terse RDF Triple Language⁠ (based on MolecularEntity profile⁠)
• ntriples - N-Triples⁠ (based on MolecularEntity profile⁠)
• rdfxml - RDF/XML⁠ (based on MolecularEntity profile⁠)
• rdfthrift - RDF Binary encoding using Thrift⁠ (based on MolecularEntity profile⁠)
• jsonldhtml - JSON-LD⁠ with HTML (based on MolecularEntity profile⁠)
• jsonld - JSON-LD⁠ (based on MolecularEntity profile⁠)
• rdfa - Simple HTML with RDFa⁠ (based on MolecularEntity profile⁠)
• microdata - Simple HTML with Microdata⁠ (based on MolecularEntity profile⁠)

⁠What is structured data

Structured data⁠ is additional data placed on websites. It is not visible to ordinary internet users but can be easily processed by machines. There are 3 formats that we can use to save structured data - JSON-LD⁠, RDFa⁠, and Microdata⁠. SDFEater supports them all and uses the MolecularEntity profile⁠.

⁠Additional examples

java -jar SDFEater-VERSION-jar-with-dependencies.jar -i ../examples/chebi_special_char_test.sdf -f cypherup

Returns Cypher⁠ with added periodic table data for atoms and replaced chemical database IDs with URL. SDFEater run from a JAR file.

java -jar SDFEater-VERSION-jar-with-dependencies.jar -i ../examples/chebi_test.sdf -f jsonld  > molecules.jsonld

Returns JSON-LD⁠ and redirects output to molecules.jsonld file. SDFEater runs from a JAR file.

docker run --rm --name sdfeater-app --mount type=bind,source=/home/user/input,target=/app/input,readonly lszeremeta/sdfeater:latest -i input/chebi_test.sdf -f microdata  > molecules.html

Returns simple HTML with added Microdata⁠ and redirects output to molecules.html file. Run from pre-build Docker image.

In the examples directory you can find example of SDF files based on data from ChEBI⁠ and DrugBank open structures⁠ databases.

⁠Publications and resources

If you need more detailed information, take a look at these publications and resources. There you will find a detailed description of the parser, performance tests, and example of Cypher outputs.

1. Ł. Szeremeta, "SDFEater: A Parser for Chemoinformatics Formats" 9 2018 [Online]. Available: https://doi.org/10.26434/chemrxiv.7123193⁠.
2. D. Tomaszuk and Ł. Szeremeta, "Named Property Graphs" in Proceedings of the 2018 Federated Conference on Computer Science and Information Systems, ser. Annals of Computer Science and Information Systems, M. Ganzha, L. Maciaszek, and M. Paprzycki, Eds., vol. 15. IEEE, 2018, pp. 173–177. (2018) [Online]. Available: http://dx.doi.org/10.15439/2018F103⁠.
3. Ł. Szeremeta and D. Tomaszuk, “SDFParser example Cypher outputs”. figshare, 10-May-2018 [Online]. Available: https://doi.org/10.6084/m9.figshare.6249962⁠.
4. D. Tomaszuk, “chemskos”. figshare, 29-Aug-2018 [Online]. Available: https://doi.org/10.6084/m9.figshare.7022144⁠.

⁠Used open source projects

• Apache Commons CLI⁠ as CLI controller (Apache License 2.0⁠),
• Gson⁠ as periodic table JSON parser (Apache License 2.0⁠),
• periodic-table⁠ - base JSON periodic table file (ISC License⁠),
• Apache Jena⁠ - for some output formats (Apache License 2.0⁠),
• Apache Commons Text⁠ - to HTML escape for RDFa and Microdata formats (Apache License 2.0⁠).

The sample SDF files in the examples and test directory are based on data from ChEBI⁠ (CC BY 4.0⁠) and DrugBank⁠ open structures (CC0 1.0⁠) databases.

⁠Contribution

Would you like to improve the SDFEater? Great! We are waiting for your help and suggestions. If you are new to open source contributions, read How to Contribute to Open Source⁠.

⁠License

Distributed under MIT License⁠.

⁠See also

These projects can also be useful:

• Molstruct⁠ - Convert chemical molecule data CSV files to structured data formats
• MEgen⁠ - Convenient online form to generate structured data about molecules