/SDFEater

Always hungry SDF chemical file format parser with many output formats

Primary LanguageJavaMIT LicenseMIT

SDFEater logo

Codacy Badge Docker Image Size (latest by date)

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:

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

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