With the 3decision API, you can attach additional files to registered structures. They will be displayed in the dedicated “FILES” panel in the Information Browser.
This section describes in details how to use the POST /structures/file/{structure_id} to attach files to a structure.
¶ Structure Files Input
To attach files to a structure, the required input of the POST /structures/file/{structure_id} endpoint is:
- the
file(s)to attach to the structure PDB.
The supported attachment file formats (also listed in the endpoint documentation):
*.as, *.bin, *.brix, *.ccp4, *.cif, *.cns, *.csv, *.cube, *.dcd, *.doc,
*.docx, *.dsn6, *.dx, *.dxbin, *.ent, *.gro, *.gif, *.hkl, *.map, *.mmcif,
*.mmtf, *.mol, *.mol2, *.mrc, *.mtz, *.ncdf, *.nctraj, *.pdb, *.pdf, *.ppt,
*.pptx, *.pqr, *.prmtop, *.sd, *.sdf, *.trr, *.txt, *.xls, *.xlsx, *.xplor,
*.xtc, *.zip, *.smi, *.log, *.lp, *.sca, *.hkl, *.out, *.ps, *.cif
- The
structure IDof the structure you want to attach files to (to retrieve the structureID from the external code, use GET /structures/code/{external_code} endpoint. See the dedicated section of this documentation for the step-by-step guide)
Notice that with the
POST /structures/file/{structure_id}endpoint you can upload a maximum of 5 files per request, and that the maximum file size is 300 MB.
¶ Add Structure Associated Files
To add a Structure Annotation from the API, you first need to access and activate the API (instructions in the Access page of this documentation).
Then, you can add a Structure Additional File to a previously registered structure, using the POST /structures/file/{structure_id} endpoint.
¶ From the 3decision API interface:
- From the activated API interface, go to the
POST /structures/file/{structure_id}endpoint - Click on "Try it out" to activate the endpoint
- Type the
structure IDof your structure in the approapriate field - Click on “Add string item” in the “files” section. This activates the button to upload the file "Choose File".
- Click on "Choose File" and select the file to attach
- (Optional) To attach multiple files, click on the button “Add string item”, and you will be able to add another file.
- Once you uploaded all the files, click on “Execute”.
¶ Using the 'curl' command:
curl -X 'POST' \
'https://3decision-<customer>-api.discngine.cloud/structures/file/775843' \
-H 'accept: application/json' \
-H 'X-API-VERSION: 1' \
-H 'Authorization: Bearer eyJhb********htE' \
-H 'Content-Type: multipart/form-data' \
-F 'files=@SearchResults.sdf'
¶ Using Python
import json
from pathlib import Path
import requests
from dng_3dec_data_import_tools.api_utils import get_requests_session
def add_additional_files(
structure_id: int, files: list[Path], session: requests.Session
) -> dict[str, int]:
"""Add additional files to a structure.
Parameters
----------
structure_id : int
Target structure database ID
files : list[Path]
List of path of files to link
session : requests.Session
Requests API session
Returns
-------
dict[str, int]
Dictionary of registered file names and associate database IDs.
"""
# Split list of files in chunck of 5 files
chunks = [files[i : i + 5] for i in range(0, len(files), 5)]
uploaded_files: dict[str, int] = {}
for chunk in chunks:
response = session.post(
url=(
"https://3decision-<customer>-api.discngine.cloud/structures/file/"
f"{structure_id}"
),
files=[("files", local_file_path.open("rb")) for local_file_path in chunk],
)
response.raise_for_status()
json_response = json.loads(response.content)
uploaded_files.update(
{
f"{file_response['file_type_label']}."
f"{file_response['file_type_extension']}": file_response["file_id"]
for file_response in json_response
}
)
return uploaded_files
if __name__ == "__main__":
session = get_requests_session()
structure_id = 1234
files = [Path("/path/to/file1.mtz"), Path("/path/to/file2.sdf")]
print(add_additional_files(structure_id, files, session))
¶ Response example
[
{
"file_id": 3419,
"file_name": "SearchResults.sdf",
"file_desc": null,
"file_type_label": "ligand",
"file_type_extension": "sdf",
"file_flag": null,
"created_by": "elisa.martino___discngine.com",
"created_date": "2023-07-17T07:57:58.000Z",
"updated_by": "elisa.martino___discngine.com",
"updated_date": "2023-07-17T07:57:58.000Z",
"structure_state_id": 1455637,
"external_code": "n7vh3h",
"cavity_id": null
}
]
The files will be displayed in the UI in the "Information Browser", in the “Structure Files” panel, where you can visualize and/or download them (depending on the file type).
