How to Import Monomers in Bulk

This guide shows how to register many monomers at once from a CSV, Excel or SDF file, follow the import, and fix the rows that failed. The worked example is a small library a peptide project typically needs: two hydrophobic replacements and two PEG linkers, one of them with a deliberate mistake.

Prerequisites: the Manager or Administrator role in Biotoolkit Monomers, and the SMILES of every monomer with its attachment points written as [*:n].

Step 1: Download the template

On the Monomers page, click Import a file. The Import monomers page opens; the Import a file quick action of the Home page leads there too. The panel on the right, What the import does, summarises the rules, and its Download the template button downloads monomer_import_template.xlsx. Start from it: the column headers must match exactly, and their order does not matter. Read the file format opens The import file dialog, with the same template button and every column with an example.

The import file dialog: the four rules of an import, the Download the template button, and the column table with the required columns, an example and the notes

Step 2: Fill in one row per monomer

The columns:

Column	Required	Content
`SYMBOL`	yes	The symbol HELM sequences will use. Unique within your organisation for the polymer type, and not held by a public monomer.
`NAME`	yes	Full name.
`SMILES`	yes	Structure with `[*:n]` attachment points.
`POLYMER_TYPE`	yes	`PEPTIDE`, `RNA` or `CHEM`.
`MONOMER_TYPE`	yes	`Backbone` or `Branch`; `Undefined` for `CHEM`.
`NATURAL_ANALOG`	for `PEPTIDE` and `RNA`	Single-letter code of the natural residue, for example `L`. `-` for `CHEM`.
`AUTHOR`	no	Free text.
`RGROUPS`	no	Cap group per attachment point, as `R1:H;R2:OH`.
`ALIASES`	no	Other names of the monomer, separated by `/`, as `NMeNva/N-Me-Nva`. Added, never removed. See How to Manage Monomer Aliases.

The full column reference is in Import File Format.

The example library:

SYMBOL	NAME	SMILES	POLYMER_TYPE	MONOMER_TYPE	NATURAL_ANALOG	RGROUPS
`Ahp`	2-Aminoheptanoic acid	`CCCCC[C@H](N[:1])C([:2])=O`	`PEPTIDE`	`Backbone`	`L`	`R1:H;R2:OH`
`MeNva`	N-methyl-norvaline	`CCC[C@H](N(C)[:1])C([:2])=O`	`PEPTIDE`	`Backbone`	`V`	`R1:H;R2:OH`
`PEG2`	Diethylene glycol linker	`[:1]OCCOCCO[:2]`	`CHEM`	`Undefined`	`-`	`R1:H;R2:OMe`
`PEG3`	Triethylene glycol linker	`[:1]OCCOCCOCCO[:2]`	`CHEM`	`Undefined`	`-`	`R1:H;R2:H`

Three things to check in your own rows:

The symbol is free. The public library already holds the common non-natural residues: norleucine is Nle, norvaline is Nva, sarcosine is meG, 2-aminoisobutyric acid is Aib. A row that reuses a public symbol fails, and a row whose structure is already public fails too. Browse the Monomers page, or search the name, before inventing a symbol. See Public Monomers.
Attachment points are numbered. [*] without a number is not an attachment point.
Cap groups come from the vocabulary. H, OH, NH2, Azide and Ethynyl are shipped, and your organisation can add its own on the Cap groups page. The PEG2 row above uses OMe, which is not one of them, on purpose: it is the row that will fail. See Attachment Points and CAP Groups.

Save the file as .xlsx, .csv or .sdf. In an SDF, each record is one monomer: its SMILES data field is the structure when it has one, otherwise its molfile, and the other data fields carry the other columns; see Import File Format.

Step 3: Upload the file

On the Import monomers page, drop the file on the Drop a file here, or browse zone or click it to browse, then click Import the file. Leave Register a known structure as an alias off for a first import: with it on, a row whose structure is already registered becomes an alias of that monomer instead of failing, which is useful once you know the duplicates are naming differences. See How to Manage Monomer Aliases.

For an SD file, leave Read stereo without chiral flag as racemic on unless the file comes from a program that writes single enantiomers without the chiral flag. With it on, a record read from its molfile that draws stereocentres without the flag is registered as a racemate (&1), the MDL standard; off, as drawn. See Enhanced Stereochemistry.

Import the file asks for confirmation, recalling how the rows will be registered under these options. Click Import. The import runs in the background: the page returns immediately, and the Import history report below refreshes every few seconds until the import finishes.

The Import monomers page: the drop zone, the Register a known structure as an alias and Read stereo without chiral flag as racemic switches, the Import the file button, the What the import does panel, and the Import history report with the finished file, its status Done with errors, its row bar and the 1 error link in the Error file column

Each row of Import history is one file. Status shows where it stands, Rows gives the counts under a bar, green for the imported rows and red for the refused ones, Duration how long it took, and Error file holds the download when rows were refused. Show more columns from the report's Actions menu if you want the parsed, imported and refused counts side by side, or the one-line Summary.

A short delay between the upload and the appearance of the monomers on the Monomers page is normal: each structure is validated and drawn by the Biotoolkit service before it is stored.

Step 4: Read the outcome

The file above ends with Status Done, with errors and Rows 3 imported, 1 refused, of 4. The status is about the file: a single refused row is enough for Done, with errors, and the three other monomers are in the library all the same.

A row of your file has one of three outcomes:

Succeeded, created. The symbol did not exist for that polymer type in your organisation.
Succeeded, updated. A private monomer with the same symbol and polymer type already existed, and the file's values replaced it. If the structure or the classification changed, the previous state is archived as a version. See Versioning and Deletion.
Failed. The row was rejected. It does not stop the other rows.

Public monomers are never touched by an import, and a row that carries the symbol or the structure of a public monomer fails.

On the Monomers page, monomers created by an import show Unknown in Created by. The Import history row is where the uploader is recorded.

Step 5: Fix the failed rows

When at least one row failed, the Error file column of Import history shows the number of refused rows as a link, 1 error here; click it to download the error file. It holds the failed rows of your file with one extra column, ERROR_MESSAGE.

For the PEG2 row it reads:

Invalid cap group "OME" for R2. Valid values: Azide, Ethynyl, H, NH2, OH

The list holds your organisation's own cap groups too, when it has some.

Correct the value to R2:H in your file, keep only that row, and upload it again. Re-importing a row that already succeeded is harmless: it is reported as updated, and no version is written when nothing material changed.

The messages you are most likely to meet:

Message	Cause
`Symbol is required`, `Name is required`, `SMILES is required`, `Polymer type is required`, `Monomer type is required`	A mandatory column is empty on that row.
`Unknown polymer type: …` / `Unknown monomer type: …`	A value outside the lists. The message ends with the expected values.
`Invalid cap group "…" for R2. Valid values: …`	A cap outside the vocabulary.
`Invalid R-group format "…". Expected format: R1:H or R2:OH`	A pair in `RGROUPS` is not `label:cap`.
`Cannot modify protected public monomer 'Nva' (public seed data)`	A public monomer holds that symbol. Use it, or choose another symbol.
`Monomer with this structure is already registered: …`	The same structure is already registered under another symbol, yours or public. If your symbol is just another name for it, import the row again with Register a known structure as an alias on.
`Monomer with this name is already registered: … (symbol: …)`	Another of your monomers of the polymer type has this `NAME`.
`"…" is already an alias of monomer …`	The row's `SYMBOL` is already an alias. Use that monomer, or choose another symbol.
`Monomer … was created, but alias "…" was not added: …`	The monomer is in the library, but one name of its `ALIASES` cell is taken by another monomer. Fix the cell and import the row again.
`Enhanced stereochemistry on bonds (the MDLV30/STEB… collection …) is not supported …`	An SD record's molfile carries an E/Z or atropisomer group the library cannot store. Register each isomer as its own record.
`Axial chirality is not supported (the stereo on atom …) …`	The structure is an atropisomer, an allene or a spiro[3.3]heptane drawn with its axial stereo. Remove that stereo.
`The record has no molfile (no 'M END' line)`	An SD record has neither a `SMILES` field nor a molfile.

If the message is An error has occurred, check your file format … at upload time, the file itself could not be read: check the extension, the header row, and that the file is not empty.

Next steps

Check a single monomer, or correct one by hand: How to Create or Edit a Monomer.