ACPype_API_Reference.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "private_outputs": true,
      "provenance": [],
      "collapsed_sections": [
        "42Dx-W2PhNvX",
        "sZmMu11IhXYR",
        "MuQBcdstMOQA",
        "aU_uwwgye4qJ"
      ],
      "authorship_tag": "ABX9TyPB+Hq+CQfyJnK2Zx9oFMHz",
      "include_colab_link": true
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "view-in-github",
        "colab_type": "text"
      },
      "source": [
        "<a href=\"https://colab.research.google.com/github/Bio2Byte/public_notebooks/blob/main/ACPype_API_Reference.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "# ACPYPE API Reference\n",
        "\n",
        "[ACPYPE](https://bio2byte.be/acpype/) provides a user-friendly HTTP API that allows users to submit molecules in a variety of formats for processing using the ACPYPE software.\n",
        "\n",
        "Our API enables users to specify a wide range of options for processing, including charge method, net charge, and atom type.\n",
        "\n",
        "After submitting their molecule, users can query the result files generated by ACPYPE in the background using a simple hash ID.\n",
        "\n",
        "![https://bio2byte.be/static_tools/images/workflow_acpype.jpg](https://bio2byte.be/static_tools/images/workflow_acpype.jpg)\n",
        "\n",
        "## About ACPYPE\n",
        "\n",
        "The ACPYPE Portal was designed to generate topology parameters files for unusual organic chemical compounds. It is based on ANTECHAMBER and so far, ACPYPE is able to work for CNS/XPLOR, GROMACS, CHARMM and AMBER.\n",
        "\n",
        "The main scope for ACPYPE Server is to help to pave the way for automatic molecular dynamics simulations involving molecules with unknown parameters, like for example, in complexes of protein and inhibitor, where the ligand is usually an unusual chemical compound.\n",
        "\n",
        "ACPYPE stands for AnteChamber PYthon Parser interfacE and is pronounced \"ace + pipe\".\n",
        "\n",
        "### What the ACPYPE Server does\n",
        "It will take either a SMILES input or files in format PDB, MDL or MOL2 of a small organic molecule without open valence and assign charges and force ﬁeld parameterizations according to GAFF (Generalised Amber Force Field). There are some options that can be applied to a submitting project.\n",
        "For charge, there are three methods:\n",
        "\n",
        "bcc: for semi-epirical AM1-BCC, parameterized to reproduce HF/6- 31G* RESP charges; slow, but with good cost/benefit (default)\n",
        "Gasteiger method, very fast but less accurate\n",
        "user: for a MOL2 file with charges already calculated, via, e.g., R.E.D.-III\n",
        "For net charge, set a integer value for the project, or let ACPYPE guess the net charge for the molecule.\n",
        "For atom type, set GAFF (default), GAFF2 or AMBER. If set AMBER, ACPYPE/antechamber will try to set parameters and atom types according to AMBER14SB forcefield. Case it fails, GAFF parameters (but with AMBER atom types) will be used.\n",
        "\n",
        "### What the ACPYPE Server doesn't do\n",
        "It will not work with organic molecule with open valences; containing others atoms than C, N, O, S, P, H, F, Cl, Br and I; or covalently bonded to another molecule. If one wants parameters for a modified amino acid residue, one way of getting it is by neutralising the N- and C- termini and then fit manually the additional parameters to the modified residue.\n",
        "\n",
        "### Citations\n",
        "If you use this resource, please cite:\n",
        "\n",
        "> SOUSA DA SILVA, A. W. & VRANKEN, W. F. ACPYPE - AnteChamber PYthon Parser interfacE. BMC Research Notes 2012, 5:367\n",
        "KAGAMI, L. P., SOUSA DA SILVA, A. W., DÍAZ, A., & VRANKEN, W. F. The ACPYPE web server for small molecule MD topology generation. Manuscript submitted.\n",
        "If you use non-uniform 1-4 scale factor conversion (e.g. if using GLYCAM06), please cite:\n",
        "\n",
        "> BERNARDI, A., FALLER, R., REITH, D., and KIRSCHNER, K. N. ACPYPE update for nonuniform 1-4 scale factors: Conversion of the GLYCAM06 force field from AMBER to GROMACS. SoftwareX 10 (2019), 100241.\n",
        "\n",
        "### Disclaimer\n",
        "This service is provided with ABSOLUTELY NO WARRANTY and holds no liabilities. If you decide to use it, bear in mind that your data and potential results are not stored with encryption, and the service administration has access to it. Furthermore, the data and results will be eventually removed after two weeks from the time of submission, whether your job has finished or not."
      ],
      "metadata": {
        "id": "Sd18WMA-LMw6"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Submitting a ligand\n",
        "Depending on your input, please execute one of the two available scenarios."
      ],
      "metadata": {
        "id": "URKKUNUuLWlq"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "A4XSVcRrLMHv"
      },
      "outputs": [],
      "source": [
        "# Import the necessary libraries\n",
        "import json\n",
        "import requests"
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "location = None\n",
        "hash_id = None"
      ],
      "metadata": {
        "id": "8ZCpOe2ndTDf"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Scenario A: Using SMILES representation"
      ],
      "metadata": {
        "id": "42Dx-W2PhNvX"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "url = \"https://bio2byte.be/acs/api\"\n",
        "print(\"POST\", url)\n",
        "\n",
        "# Define request payload\n",
        "payload = {\n",
        "    \"inputFile\": None,\n",
        "    \"file_name\": \"OXYGEN_FROM_API\",\n",
        "    \"token\": \"RTV5GZHc5M\",\n",
        "    \"charge_method\": \"bbc\",\n",
        "    \"net_charge\": None,\n",
        "    \"atom_type\": \"gaff\",\n",
        "    \"email\": None,\n",
        "    \"smiles\": \"O\"\n",
        "}\n",
        "\n",
        "# Send POST request\n",
        "response = requests.post(url, json=payload)\n",
        "\n",
        "# Process the response\n",
        "if response.status_code > 200 and response.status_code < 300:\n",
        "    data = response.json()\n",
        "    location = data[\"Location\"]\n",
        "    hash_id = data[\"hash_id\"]\n",
        "    message = data[\"message\"]\n",
        "    print(\"Prediction job submitted successfully!\")\n",
        "    print(f\"Location: {location}\")\n",
        "    print(f\"hash_id: {hash_id}\")\n",
        "    print(f\"Message: {message}\")\n",
        "else:\n",
        "    print(\"Failed to submit prediction job. Status Code:\", response.status_code)"
      ],
      "metadata": {
        "id": "DXTpdk-qLVah"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Scenario B: Using a file with coordinates\n",
        "Please upload to Google Colab your input file (PDB, MDL or MOL2 of a small organic molecule)"
      ],
      "metadata": {
        "id": "sZmMu11IhXYR"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "url = \"https://bio2byte.be/acs/api\"\n",
        "print(\"POST\", url)\n",
        "\n",
        "with open(\"/content/EXAMPLE.pdb\", \"rb\") as input_file_handler:\n",
        "    file_content = input_file_handler.read().decode(\"utf-8\")\n",
        "\n",
        "# Define request payload\n",
        "payload = {\n",
        "    \"inputFile\": file_content,\n",
        "    \"file_name\": \"EXAMPLE.pdb\",\n",
        "    \"token\": \"RTV5GZHc5M\",\n",
        "    \"charge_method\": \"bbc\",\n",
        "    \"net_charge\": None,\n",
        "    \"atom_type\": \"gaff\",\n",
        "    \"email\": None,\n",
        "    \"smiles\": None\n",
        "}\n",
        "\n",
        "# Send POST request\n",
        "response = requests.post(url, json=payload)\n",
        "\n",
        "# Process the response\n",
        "if response.status_code > 200 and response.status_code < 300:\n",
        "    data = response.json()\n",
        "    location = data[\"Location\"]\n",
        "    hash_id = data[\"hash_id\"]\n",
        "    message = data[\"message\"]\n",
        "    print(\"Prediction job submitted successfully!\")\n",
        "    print(f\"Location: {location}\")\n",
        "    print(f\"hash_id: {hash_id}\")\n",
        "    print(f\"Message: {message}\")\n",
        "else:\n",
        "    print(\"Failed to submit prediction job. Status Code:\", response.status_code)"
      ],
      "metadata": {
        "id": "IOB_sR1phXHR"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Querying the submission status via Hash ID"
      ],
      "metadata": {
        "id": "MuQBcdstMOQA"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "url = f\"https://bio2byte.be/acs{location}\"\n",
        "print(\"GET\", url)\n",
        "\n",
        "# Make the API request and store the JSON response in a variable\n",
        "response = requests.get(url)\n",
        "\n",
        "# Check the response status code\n",
        "if response.status_code >= 400:\n",
        "    print(\"Failed to fetch prediction job. Response status Code:\", response.status_code)\n",
        "elif response.status_code >= 202:\n",
        "    print(\"Still processing your request. Please try again in a minute. Response status code: \", response.status_code)\n",
        "\n",
        "    # Extract the JSON response\n",
        "    json_response = response.json()\n",
        "    print(json_response)\n",
        "else:\n",
        "    print(\"Response status code:\", response.status_code)\n",
        "    # Extract the JSON response\n",
        "    json_response = response.json()\n",
        "\n",
        "    id = json_response['id']\n",
        "    creation_date = json_response['creation_date']\n",
        "    token = json_response['token']\n",
        "    hash_id = json_response['hash_id']\n",
        "    result_request = json_response['result_request']\n",
        "    location = result_request['location']\n",
        "    status = result_request['status']\n",
        "\n",
        "    print(\"Response fields:\")\n",
        "    print(f\"id: {id}\")\n",
        "    print(f\"creation_date: {creation_date}\")\n",
        "    print(f\"token: {token}\")\n",
        "    print(f\"hash_id: {hash_id}\")\n",
        "    print(f\"location: {location}\")\n",
        "    print(f\"status: {status}\")\n",
        "    \n",
        "    print(\"You job files are available!\")"
      ],
      "metadata": {
        "id": "B1vKIdBeMNw0"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Fetching the submission results via Hash ID"
      ],
      "metadata": {
        "id": "aU_uwwgye4qJ"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Make the API request and store the JSON response in a variable\n",
        "url = f\"https://bio2byte.be/acs/api/{hash_id}/\"\n",
        "print(\"GET\", url)\n",
        "\n",
        "response = requests.get(url)\n",
        "\n",
        "# Check the response status code\n",
        "if response.status_code >= 400:\n",
        "    # Display an error message if the request fails\n",
        "    print(\"Failed to fetch prediction job. Status Code:\", response.status_code)\n",
        "elif response.status_code >= 300:\n",
        "    print(\"Still working on the prediction job, please try again in a minute. Status Code:\", response.status_code)\n",
        "else:\n",
        "    # Extract the JSON response\n",
        "    json_response = response.json()\n",
        "\n",
        "    # Loop through each result and save it to a separate file\n",
        "    for i, result in enumerate(json_response[\"results\"], start=1):\n",
        "        for key, value in result.items():\n",
        "            \n",
        "            # Save each result to a file\n",
        "            print(f\"Saving {key} content to result_{i}_{key}.txt\")\n",
        "            \n",
        "            with open(f\"result_{i}_{key}.txt\", \"w\") as f:\n",
        "                f.write(value)\n",
        "    \n",
        "    print(\"Files saved with success\")"
      ],
      "metadata": {
        "id": "Q9N7GnJIbhaO"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "# Compress the result files\n",
        "!zip -r acpype_results.zip /content/*.txt\n",
        "\n",
        "# Download results\n",
        "from google.colab import files\n",
        "files.download(\"/content/acpype_results.zip\")"
      ],
      "metadata": {
        "id": "kSmDEJkPfyRR"
      },
      "execution_count": null,
      "outputs": []
    }
  ]
}