{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8bf12d3d-2615-42af-b2a1-aad3b715497c",
   "metadata": {},
   "source": [
    "# Updating submitted samples\n",
    "\n",
    "A pretty cool thing about BioSamples is that you can always update the sample after submission. Let's say you've got a sample, and you want to add a couple extra fields; you looked into your lab notebook and finally deciphered those scribbles that you thought was either elf language or LSD exposition.\n",
    "\n",
    "The `BsdApi` makes it even simpler; you just need to retrieve your samples, update them as needed, and send the list back to the `update` function.\n",
    "\n",
    "**IMPORTANT NOTE**: Biosamples does **NOT** accept patch requests. What this means in plain english is: You replace the sample completely when updating. Please take that into account when performing updates!\n",
    "\n",
    "## Set-up and retrieve existing samples"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "438b3a86-3f71-4ea6-8e6e-03d88e90a703",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2024-10-14 10:46:04,052 - BsdApi - INFO - Set up BSD API successfully: using base uri 'https://wwwdev.ebi.ac.uk/biosamples/samples'\n",
      "2024-10-14 10:46:04,052 - BsdApi - INFO - Trying to retrieve sample with accession SAMEA131394580\n"
     ]
    }
   ],
   "source": [
    "## Import everything we need\n",
    "from biobroker.authenticator import WebinAuthenticator # Biosamples uses the WebinAuthenticator\n",
    "from biobroker.api import BsdApi # BioSamples Database (BSD) API\n",
    "import os\n",
    "\n",
    "os.environ['API_ENVIRONMENT'] = \"dev\" # There are multiple ways to set up environment variables\n",
    "\n",
    "username = \"\" # Your username goes here\n",
    "password = \"\" # Your password goes here\n",
    "authenticator = WebinAuthenticator(username=username, password=password)\n",
    "\n",
    "api = BsdApi(authenticator=authenticator)\n",
    "\n",
    "my_sample = api.retrieve(['SAMEA131394580'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3984a398-765a-4a73-8f1b-19fa8cbce467",
   "metadata": {},
   "source": [
    "Now that we got the samples, let's apply the modifications!\n",
    "\n",
    "For this example, I will be adding a new field with the same value (I won't be going through the work of making multiple values, this is just an example of what you can do)\n",
    "\n",
    "Please note that you can use an **output processor** to get your samples back in tsv/xlsx format, modify them, load them back with an **input processor** and perform the update operation. It's very intuitive and very simple, for those modifications that need an extra non-programmatic eye!\n",
    "\n",
    "(But I am not doing that because that would involve more work and making screenshots. Nope)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "26947b44-96c9-4de9-a434-1c8f62df99aa",
   "metadata": {},
   "outputs": [],
   "source": [
    "for sample in my_sample:\n",
    "    sample['myNewField'] = \"aNewValue\"\n",
    "\n",
    "my_updated_sample = api.update(my_sample)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "03e6caf5-b999-4c4f-a1d1-709f43cb6f8b",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'characteristics': {'SRA accession': [{'text': 'ERS30993787'}], 'collected_at': [{'text': 'noon'}], 'myNewField': [{'text': 'aNewValue'}], 'organism': [{'text': 'Homo sapiens'}]}, 'name': 'sumple', 'accession': 'SAMEA131394580', 'release': '2024-09-26T07:52:45Z', 'sraAccession': 'ERS30993787', 'webinSubmissionAccountId': 'Webin-64342', 'taxId': 9606, 'status': 'PUBLIC', 'update': '2024-10-14T09:46:43.551Z', 'submitted': '2024-09-26T08:03:34.403Z', 'submittedVia': 'JSON_API', 'create': '2024-09-26T08:03:34.403Z', '_links': {'self': {'href': 'https://wwwdev.ebi.ac.uk/biosamples/samples/SAMEA131394580'}, 'curationDomain': {'href': 'https://wwwdev.ebi.ac.uk/biosamples/samples/SAMEA131394580{?curationdomain}', 'templated': True}, 'curationLinks': {'href': 'https://wwwdev.ebi.ac.uk/biosamples/samples/SAMEA131394580/curationlinks'}, 'curationLink': {'href': 'https://wwwdev.ebi.ac.uk/biosamples/samples/SAMEA131394580/curationlinks/{hash}', 'templated': True}, 'structuredData': {'href': 'https://wwwdev.ebi.ac.uk/biosamples/structureddata/SAMEA131394580'}}}\n"
     ]
    }
   ],
   "source": [
    "print(my_updated_sample[0].entity)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53e8f0c3-a0e7-43d6-930b-f047b2c49637",
   "metadata": {},
   "source": [
    "Pretty easy, right?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}