cross-link_ms-ambiguity.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "How to deal with ambiguity<a id=\"cross-link_ms-ambiguity\"></a>\n",
        "==========================\n",
        "\n",
        "**Table of contents**\n",
        "\n",
        " - [1. Cross-link identification ambiguity](#autotoc2v1)\n",
        " - [2. Compositional ambiguity](#autotoc2v2)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "> This tutorial continues on from the [introduction to cross-linking](cross-link_ms.ipynb) tutorial.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "There are several way one can deal with ambiguity of XL-MS data. Let's define the possible ambiguities:\n",
        "\n",
        " 1. cross-link identification ambiguity\n",
        " 2. compositional ambiguity\n",
        " 3. state ambiguity"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "from __future__ import print_function\n",
        "\n",
        "import IMP\n",
        "import IMP.pmi\n",
        "import IMP.pmi.topology\n",
        "import IMP.pmi.io\n",
        "import IMP.pmi.io.crosslink"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "# 1. Cross-link identification ambiguity<a id=\"autotoc2v1\"></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "There are several models on how to implement the identification ambiguity.\n",
        "\n",
        "One way to do it is to use the `UniqueID` keyword; cross-links with the same UniqueID are considered ambiguous:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [],
      "source": [
        "xldb='''Protein 1,Protein 2,Residue 1,Residue 2,UniqueID,Score\n",
        "ProtA,ProtB,1,10,1,1.0\n",
        "ProtA,ProtB,1,11,1,2.0\n",
        "ProtA,ProtB,1,21,2,2.0\n",
        "'''\n",
        "\n",
        "with open('xlinks.csv', 'w') as xlf:\n",
        "    xlf.write(xldb)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "In the example above, cross-links ProtA:1-ProtB:10 and ProtA:1-ProtB:11 are ambiguous because they were assigned to the same UniqueID.\n",
        "\n",
        "Now we create a conversion map between internal keywords of xlinks features and the one in the file:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [],
      "source": [
        "cldbkc = IMP.pmi.io.crosslink.CrossLinkDataBaseKeywordsConverter()\n",
        "cldbkc.set_protein1_key(\"Protein 1\")\n",
        "cldbkc.set_protein2_key(\"Protein 2\")\n",
        "cldbkc.set_residue1_key(\"Residue 1\")\n",
        "cldbkc.set_residue2_key(\"Residue 2\")\n",
        "cldbkc.set_unique_id_key(\"UniqueID\")\n",
        "cldbkc.set_id_score_key(\"Score\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "With this keyword interpreter, let's read the cross-link database:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [],
      "source": [
        "cldb = IMP.pmi.io.crosslink.CrossLinkDataBase(cldbkc)\n",
        "cldb.create_set_from_file(\"xlinks.csv\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "Let's check that the database looks ok:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "1\n",
            "--- XLUniqueID 1\n",
            "--- XLUniqueSubIndex 1\n",
            "--- XLUniqueSubID 1.1\n",
            "--- Protein1 ProtA\n",
            "--- Protein2 ProtB\n",
            "--- Residue1 1\n",
            "--- Residue2 10\n",
            "--- IDScore 1.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['1.1']\n",
            "--- Ambiguity 2\n",
            "--- Residue1LinksNumber 3\n",
            "--- Residue2LinksNumber 1\n",
            "-------------\n",
            "--- XLUniqueID 1\n",
            "--- XLUniqueSubIndex 2\n",
            "--- XLUniqueSubID 1.2\n",
            "--- Protein1 ProtA\n",
            "--- Protein2 ProtB\n",
            "--- Residue1 1\n",
            "--- Residue2 11\n",
            "--- IDScore 2.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['1.2']\n",
            "--- Ambiguity 2\n",
            "--- Residue1LinksNumber 3\n",
            "--- Residue2LinksNumber 1\n",
            "-------------\n",
            "2\n",
            "--- XLUniqueID 2\n",
            "--- XLUniqueSubIndex 1\n",
            "--- XLUniqueSubID 2.1\n",
            "--- Protein1 ProtA\n",
            "--- Protein2 ProtB\n",
            "--- Residue1 1\n",
            "--- Residue2 21\n",
            "--- IDScore 2.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['2.1']\n",
            "--- Ambiguity 1\n",
            "--- Residue1LinksNumber 3\n",
            "--- Residue2LinksNumber 1\n",
            "-------------\n"
          ]
        }
      ],
      "source": [
        "print(cldb)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "As you can see there are two unique indexes, 1 and 2. The first spectral index contains two identifications, with subindexes 1.1 and 1.2, corresponding to the two ambiguous restraints."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# 2. Compositional ambiguity<a id=\"autotoc2v2\"></a>"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "Compositional ambiguity occurs when identical copies of the same protein are present in the sample, and we are not able to attribute the cross-link to one or the other copy.\n",
        "\n",
        "Let's suppose we already have an identification ambiguity, to complicate the example, and see how the two ambiguities combine with each other. See the data below; note that two cross-links have the same UniqueID:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [],
      "source": [
        "xldb='''Protein 1,Protein 2,Residue 1,Residue 2,UniqueID,Score\n",
        "ProtA,ProtB,1,10,1,1.0\n",
        "ProtA,ProtB,1,11,1,2.0\n",
        "ProtB,ProtA,21,1,2,2.0\n",
        "ProtA,ProtA,1,2,3,3.0\n",
        "'''\n",
        "\n",
        "with open('xlinks.csv', 'w') as xlf:\n",
        "    xlf.write(xldb)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "We will first create a database:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [],
      "source": [
        "cldbkc = IMP.pmi.io.crosslink.CrossLinkDataBaseKeywordsConverter()\n",
        "cldbkc.set_protein1_key(\"Protein 1\")\n",
        "cldbkc.set_protein2_key(\"Protein 2\")\n",
        "cldbkc.set_residue1_key(\"Residue 1\")\n",
        "cldbkc.set_residue2_key(\"Residue 2\")\n",
        "cldbkc.set_unique_id_key(\"UniqueID\")\n",
        "cldbkc.set_id_score_key(\"Score\")\n",
        "\n",
        "cldb = IMP.pmi.io.crosslink.CrossLinkDataBase(cldbkc)\n",
        "cldb.create_set_from_file(\"xlinks.csv\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "Now, we know that there are two copies of ProtA, which we called ProtA.1 and ProtA.2 in our IMP [Hierarchy](https://integrativemodeling.org/2.21.0/doc/ref/classIMP_1_1atom_1_1Hierarchy.html). Let's rename ProtA into ProtA.1 for both ends of each cross-link:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [],
      "source": [
        "from IMP.pmi.io.crosslink import FilterOperator as FO\n",
        "import operator\n",
        "\n",
        "fo1 = FO(cldb.protein1_key, operator.eq, \"ProtA\")\n",
        "cldb.set_value(cldb.protein1_key, \"ProtA.1\", fo1)\n",
        "fo2 = FO(cldb.protein2_key, operator.eq, \"ProtA\")\n",
        "cldb.set_value(cldb.protein2_key, \"ProtA.1\", fo2)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "Next we clone all cross-links involving ProtA.1 so that they were observed also by ProtA.2:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [],
      "source": [
        "cldb.clone_protein(\"ProtA.1\", \"ProtA.2\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "Let's check that the database looks OK:"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "1\n",
            "--- XLUniqueID 1\n",
            "--- XLUniqueSubIndex 1\n",
            "--- XLUniqueSubID 1.1\n",
            "--- Protein1 ProtA.1\n",
            "--- Protein2 ProtB\n",
            "--- Residue1 1\n",
            "--- Residue2 10\n",
            "--- IDScore 1.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['1.1']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n",
            "--- XLUniqueID 1\n",
            "--- XLUniqueSubIndex 2\n",
            "--- XLUniqueSubID 1.2\n",
            "--- Protein1 ProtA.2\n",
            "--- Protein2 ProtB\n",
            "--- Residue1 1\n",
            "--- Residue2 10\n",
            "--- IDScore 1.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['1.2']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n",
            "--- XLUniqueID 1\n",
            "--- XLUniqueSubIndex 3\n",
            "--- XLUniqueSubID 1.3\n",
            "--- Protein1 ProtA.1\n",
            "--- Protein2 ProtB\n",
            "--- Residue1 1\n",
            "--- Residue2 11\n",
            "--- IDScore 2.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['1.3']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n",
            "--- XLUniqueID 1\n",
            "--- XLUniqueSubIndex 4\n",
            "--- XLUniqueSubID 1.4\n",
            "--- Protein1 ProtA.2\n",
            "--- Protein2 ProtB\n",
            "--- Residue1 1\n",
            "--- Residue2 11\n",
            "--- IDScore 2.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['1.4']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n",
            "2\n",
            "--- XLUniqueID 2\n",
            "--- XLUniqueSubIndex 1\n",
            "--- XLUniqueSubID 2.1\n",
            "--- Protein1 ProtB\n",
            "--- Protein2 ProtA.1\n",
            "--- Residue1 21\n",
            "--- Residue2 1\n",
            "--- IDScore 2.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['2.1']\n",
            "--- Ambiguity 2\n",
            "--- Residue1LinksNumber 2\n",
            "--- Residue2LinksNumber 5\n",
            "-------------\n",
            "--- XLUniqueID 2\n",
            "--- XLUniqueSubIndex 2\n",
            "--- XLUniqueSubID 2.2\n",
            "--- Protein1 ProtB\n",
            "--- Protein2 ProtA.2\n",
            "--- Residue1 21\n",
            "--- Residue2 1\n",
            "--- IDScore 2.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['2.2']\n",
            "--- Ambiguity 2\n",
            "--- Residue1LinksNumber 2\n",
            "--- Residue2LinksNumber 5\n",
            "-------------\n",
            "3\n",
            "--- XLUniqueID 3\n",
            "--- XLUniqueSubIndex 1\n",
            "--- XLUniqueSubID 3.1\n",
            "--- Protein1 ProtA.1\n",
            "--- Protein2 ProtA.1\n",
            "--- Residue1 1\n",
            "--- Residue2 2\n",
            "--- IDScore 3.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['3.1']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n",
            "--- XLUniqueID 3\n",
            "--- XLUniqueSubIndex 2\n",
            "--- XLUniqueSubID 3.2\n",
            "--- Protein1 ProtA.2\n",
            "--- Protein2 ProtA.1\n",
            "--- Residue1 1\n",
            "--- Residue2 2\n",
            "--- IDScore 3.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['3.2']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n",
            "--- XLUniqueID 3\n",
            "--- XLUniqueSubIndex 3\n",
            "--- XLUniqueSubID 3.3\n",
            "--- Protein1 ProtA.1\n",
            "--- Protein2 ProtA.2\n",
            "--- Residue1 1\n",
            "--- Residue2 2\n",
            "--- IDScore 3.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['3.3']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n",
            "--- XLUniqueID 3\n",
            "--- XLUniqueSubIndex 4\n",
            "--- XLUniqueSubID 3.4\n",
            "--- Protein1 ProtA.2\n",
            "--- Protein2 ProtA.2\n",
            "--- Residue1 1\n",
            "--- Residue2 2\n",
            "--- IDScore 3.0\n",
            "--- Redundancy 1\n",
            "--- RedundancyList ['3.4']\n",
            "--- Ambiguity 4\n",
            "--- Residue1LinksNumber 5\n",
            "--- Residue2LinksNumber 2\n",
            "-------------\n"
          ]
        }
      ],
      "source": [
        "print(cldb)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "jupyter": {
          "outputs_hidden": false
        }
      },
      "source": [
        "As you can see there are three unique indexes, 1, 2 and 3. The first index contains four cross-links, \n",
        "the second two cross-links and the third four cross-links."
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.7.6"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 4
}