{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The nmrstarlib Tutorial\n",
    "=======================\n",
    "\n",
    "The :mod:`nmrstarlib` package provides classes and other facilities for parsing,\n",
    "accessing, and manipulating data stored in NMR-STAR and JSONized NMR-STAR formats.\n",
    "Also, the :mod:`nmrstarlib` package provides simple command-line interface."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Using nmrstarlib as a library\n",
    "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n",
    "\n",
    "Importing nmrstarlib package\n",
    "----------------------------\n",
    "\n",
    "If the :mod:`nmrstarlib` package is installed on the system, it can be imported:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import nmrstarlib"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Constructing StarFile generator\n",
    "-------------------------------\n",
    "\n",
    "The :mod:`~nmrstarlib.nmrstarlib` module provides the :func:`~nmrstarlib.fileio.read_files`\n",
    "generator function that yields :class:`~nmrstarlib.nmrstarlib.StarFile` instances. Constructing a\n",
    ":class:`~nmrstarlib.nmrstarlib.StarFile` generator is easy - specify the path to a local NMR-STAR file,\n",
    "directory of NMR-STAR files, archive of NMR-STAR files or BMRB id:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import nmrstarlib\n",
    "\n",
    "single_starfile = nmrstarlib.read_files(\"bmr18569.str\")  # single NMR-STAR file\n",
    "starfiles = nmrstarlib.read_files(\"bmr18569.str\", \"bmr336.str\") # several NMR-STAR files\n",
    "dir_starfiles = nmrstarlib.read_files(\"starfiles_dir\")   # directory of NMR-STAR files\n",
    "arch_starfiles = nmrstarlib.read_files(\"starfiles.zip\")  # archive of NMR-STAR files\n",
    "url_starfile = nmrstarlib.read_files(\"18569\")            # BMRB id of NMR-STAR file"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Processing StarFile generator\n",
    "-----------------------------\n",
    "\n",
    "The :class:`~nmrstarlib.nmrstarlib.StarFile` generator can be processed in several ways:\n",
    "\n",
    "* Feed it to a for-loop and process one file at a time:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for starfile in nmrstarlib.read_files(\"18569\", \"15000\"):\n",
    "    print(\"BMRB id:\", starfile.bmrbid)      # print BMRB id of StarFile\n",
    "    print(\"File source:\", starfile.source)  # print source of StarFile\n",
    "    for saveframe_name in starfile.keys():  # print saveframe names\n",
    "        print(\"\\t\", saveframe_name)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note:: Once the generator is consumed, it becomes empty and needs to be created again."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Since the :class:`~nmrstarlib.nmrstarlib.StarFile` generator behaves like an iterator,\n",
    "  we can call the :py:func:`next` built-in function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sf_generator = nmrstarlib.read_files(\"18569\", \"15000\")\n",
    "\n",
    "starfile1 = next(sf_generator)\n",
    "starfile2 = next(sf_generator)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note:: Once the generator is consumed, it becomes empty and needs to be created again."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert the :class:`~nmrstarlib.nmrstarlib.StarFile` generator into a :py:class:`list` of\n",
    "  :class:`~nmrstarlib.nmrstarlib.StarFile` objects:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfiles_list = list(nmrstarlib.read_files(\"18569\", \"15000\"))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. warning:: Do not convert the :class:`~nmrstarlib.nmrstarlib.StarFile` generator into a\n",
    "             :py:class:`list` if the generator can yield a large number of files, e.g.\n",
    "             several thousand, otherwise it can consume all available memory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "os.chdir('_static/nmrstarfiles')"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Accessing and manipulating data from a single StarFile\n",
    "------------------------------------------------------\n",
    "\n",
    "Since a :class:`~nmrstarlib.nmrstarlib.StarFile` is a Python :py:class:`collections.OrderedDict`,\n",
    "data can be accessed and manipulated as with any regular Python :py:class:`dict` object\n",
    "using bracket accessors."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Accessing data in :class:`~nmrstarlib.nmrstarlib.StarFile`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile = next(nmrstarlib.read_files(\"15000\"))\n",
    "\n",
    "# list StarFile-level keys, i.e. saveframe names\n",
    "list(starfile.keys())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# access \"data\" field \n",
    "starfile[\"data\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# access saveframe\n",
    "starfile[\"save_entry_information\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# list saveframe-level keys\n",
    "list(starfile[\"save_entry_information\"].keys())"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# access 'key-value' pairs within saveframes\n",
    "starfile[\"save_entry_information\"][\"Entry.Submission_date\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# access loops\n",
    "starfile[\"save_entry_information\"][\"loop_0\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# list loop-level fields\n",
    "starfile[\"save_entry_information\"][\"loop_0\"][0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# list loop-level values (list of dictionaries)\n",
    "starfile[\"save_entry_information\"][\"loop_0\"][1]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# every loop entry is accessed by index\n",
    "starfile[\"save_entry_information\"][\"loop_0\"][1][0][\"Entry_author.Family_name\"]"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Manipulating data in a :class:`~nmrstarlib.nmrstarlib.StarFile` is easy - access data\n",
    "  using bracket accessors and set a new value:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check submission date\n",
    "starfile[\"save_entry_information\"][\"Entry.Submission_date\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# change submission date\n",
    "starfile[\"save_entry_information\"][\"Entry.Submission_date\"] = \"2015-07-05\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# check that submission date is updated\n",
    "starfile[\"save_entry_information\"][\"Entry.Submission_date\"]"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Printing a :class:`~nmrstarlib.nmrstarlib.StarFile` and its components (`saveframe` and `loop` data):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile = next(nmrstarlib.read_files(\"bmr15000.str\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile.print_file(file_format=\"nmrstar\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile.print_file(file_format=\"json\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile.print_saveframe(\"save_entry_information\", file_format=\"nmrstar\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile.print_saveframe(\"save_entry_information\", file_format=\"json\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile.print_loop(\"save_entry_information\", \"loop_0\", file_format=\"nmrstar\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile.print_loop(\"save_entry_information\", \"loop_0\", file_format=\"json\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Accessing chemical shift data:\n",
    "\n",
    "  Chemical shift data can be accessed using bracket accessors as described above using a\n",
    "  `saveframe` name and `loop` name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][0][\"Atom_chem_shift.Seq_ID\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][0][\"Atom_chem_shift.Comp_ID\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][0][\"Atom_chem_shift.Atom_ID\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][0][\"Atom_chem_shift.Val\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][1][\"Atom_chem_shift.Atom_ID\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][1][\"Atom_chem_shift.Val\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][2][\"Atom_chem_shift.Atom_ID\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "starfile[\"save_assigned_chem_shift_list_1\"][\"loop_0\"][1][2][\"Atom_chem_shift.Val\"]"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Also the :class:`~nmrstarlib.nmrstarlib.StarFile` class provides a\n",
    ":meth:`~nmrstarlib.nmrstarlib.StarFile.chem_shifts_by_residue` method that organizes\n",
    "chemical shits into a :py:class:`list` of :py:class:`collections.OrderedDict` data structures\n",
    "(`keys` - sequence id, `values` - chemical shift data) - one for each protein chain,\n",
    "if multiple chains are present within the file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# access all chemical shifts\n",
    "starfile.chem_shifts_by_residue()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# access chemical shifts for \"SER\" and \"GLU\" amino acids\n",
    "starfile.chem_shifts_by_residue(amino_acids=[\"SER\", \"GLU\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# access chemical shifts for \"SER\" and \"GLU\" amino acids for \"CB\" and \"CG\" atoms \n",
    "starfile.chem_shifts_by_residue(amino_acids=[\"SER\", \"GLU\"], atoms=[\"CB\", \"CG\"])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# acceess chemical shifts for specific amino acid and specific atom\n",
    "starfile.chem_shifts_by_residue(amino_acids_and_atoms={\"SER\":[\"HA\", \"HB2\", \"HB3\"], \"ASP\": [\"CA\", \"N\"]})"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Writing data from a StarFile object into a file\n",
    "-----------------------------------------------\n",
    "\n",
    "Data from a :class:`~nmrstarlib.nmrstarlib.StarFile` can be written into file\n",
    "in original NMR-STAR format or in equivalent JSON format using\n",
    ":meth:`~nmrstarlib.nmrstarlib.StarFile.write()`:\n",
    "\n",
    "* Writing into a NMR-STAR formatted file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(\"out/bmr15000_modified.str\", \"w\") as outfile:\n",
    "    starfile.write(outfile, file_format=\"nmrstar\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Writing into a JSONized NMR-STAR formatted file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "with open(\"out/bmr15000_modified.json\", \"w\") as outfile:\n",
    "    starfile.write(outfile, file_format=\"json\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Converting NMR-STAR files\n",
    "-------------------------\n",
    "\n",
    "NMR-STAR files can be converted between the NMR-STAR file format and a JSONized NMR-STAR\n",
    "file format using :mod:`nmrstarlib.converter` and :mod:`nmrstarlib.translator` modules.\n",
    "\n",
    "One-to-one file conversions\n",
    "***************************\n",
    "\n",
    "* Converting from the NMR-STAR file format into its equivalent JSON file format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToStarFile\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToStarFile(from_path=\"18569\", to_path=\"out/bmr18569.json\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"json\"))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Converting from JSON file format into its equivalent NMR-STAR file format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToStarFile\n",
    "\n",
    "# Using generated above \"bmr18569.json\" file\n",
    "converter = Converter(StarFileToStarFile(from_path=\"bmr18569.json\", to_path=\"out/bmr18569.str\",\n",
    "                                         from_format=\"json\", to_format=\"nmrstar\"))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Many-to-many files conversions\n",
    "******************************\n",
    "\n",
    "* Converting from the directory of NMR-STAR formatted files into its equivalent\n",
    "  JSON formatted files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToStarFile\n",
    "\n",
    "converter = Converter(StarFileToStarFile(from_path=\"starfiles_dir_nmrstar\", to_path=\"out/starfiles_dir_json\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"json\"))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Converting from the directory of JSONized NMR-STAR formatted files into NMR-STAR formatted files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToStarFile\n",
    "\n",
    "converter = Converter(StarFileToStarFile(from_path=\"starfiles_dir_json\", to_path=\"out/starfiles_dir_nmrstar\",\n",
    "                                         from_format=\"json\", to_format=\"nmrstar\"))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note:: Many-to-many files and one-to-one file conversions are available.\n",
    "          See :mod:`nmrstarlib.converter` for full list of available conversions."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Creating simulated peak lists from NMR-STAR formatted files\n",
    "-----------------------------------------------------------\n",
    "\n",
    "Creating simulated peak lists without variance\n",
    "**********************************************\n",
    "\n",
    "Chemical shift values and assignment information deposited in NMR-STAR formatted\n",
    "files can be used to generate a large number of simulated peak lists for different\n",
    "types of solution and solid-state NMR experiments. Many different types\n",
    "of standard NMR experiments are defined in the `spectrum_description.json`\n",
    "configuration file. We will be using `HNcoCACB` spectrum type for the following\n",
    "examples.\n",
    "\n",
    "* Creating a zero-variance `HNcoCACB` peak list file in `sparky`-like format\n",
    "  from NMR-STAR formatted file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_HNcoCACB.txt\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"sparky\",\n",
    "                                         spectrum_name=\"HNcoCACB\"))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The generated `18569_HNcoCACB.txt` peak list file should look like the following:\n",
    "\n",
    "\n",
    ".. code:: bash\n",
    "\n",
    "   Assignment\t\tw1\t\tw2\t\tw3\n",
    "\n",
    "   SER2H-SER2N-MET1CA\t\t8.225\t\t117.197\t\t55.489\n",
    "   SER2H-SER2N-MET1CB\t\t8.225\t\t117.197\t\t32.848\n",
    "   GLU3H-GLU3N-SER2CA\t\t8.002\t\t119.833\t\t58.593\n",
    "   GLU3H-GLU3N-SER2CB\t\t8.002\t\t119.833\t\t64.057\n",
    "   THR4H-THR4N-GLU3CA\t\t8.956\t\t117.212\t\t55.651\n",
    "   THR4H-THR4N-GLU3CB\t\t8.956\t\t117.212\t\t32.952\n",
    "   ..."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Creating a zero-variance `HNcoCACB` peak list file in `json` format from a NMR-STAR formatted file:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_HNcoCACB.json\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"json\",\n",
    "                                         spectrum_name=\"HNcoCACB\"))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The generated `18569_HNcoCACB.json` peak list file should look like the following:\n",
    "\n",
    ".. code:: bash\n",
    "\n",
    "   [\n",
    "    {\"Assignment\": [\"SER2H\", \"SER2N\", \"MET1CA\"], \"Dimensions\": [8.225, 117.197, 55.489]},\n",
    "    {\"Assignment\": [\"SER2H\", \"SER2N\", \"MET1CB\"], \"Dimensions\": [8.225, 117.197, 32.848]},\n",
    "    {\"Assignment\": [\"GLU3H\", \"GLU3N\", \"SER2CA\"], \"Dimensions\": [8.002, 119.833, 58.593]},\n",
    "    {\"Assignment\": [\"GLU3H\", \"GLU3N\", \"SER2CB\"], \"Dimensions\": [8.002, 119.833, 64.057]},\n",
    "    {\"Assignment\": [\"THR4H\", \"THR4N\", \"GLU3CA\"], \"Dimensions\": [8.956, 117.212, 55.651]},\n",
    "    {\"Assignment\": [\"THR4H\", \"THR4N\", \"GLU3CB\"], \"Dimensions\": [8.956, 117.212, 32.952]},\n",
    "    ...\n",
    "   ]"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Creating simulated peak lists with variance drawn from random normal distribution\n",
    "*********************************************************************************\n",
    "\n",
    "* Creating a `HNcoCACB` peak list file in `sparky`-like format and adding\n",
    "  noise values to peak dimensions from a single source of variance, i.e.\n",
    "  100% of peaks will have chemical shift values adjusted using noise values\n",
    "  from the defined random normal distribution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "from nmrstarlib.noise import NoiseGenerator\n",
    "\n",
    "# create parameters dictionary for random normal distribution\n",
    "parameters = {\"H_loc\": [0], \"C_loc\": [0], \"N_loc\": [0],\n",
    "              \"H_scale\": [0.001], \"C_scale\": [0.01], \"N_scale\": [0.01]}\n",
    "\n",
    "# create random normal noise generator\n",
    "random_normal_noise_generator = NoiseGenerator(parameters)\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_HNcoCACB_ssv_HCN.txt\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"sparky\",\n",
    "                                         spectrum_name=\"HNcoCACB\",\n",
    "                                         noise_generator=random_normal_noise_generator))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The generated `18569_HNcoCACB_ssv_HCN.txt` peak list file should look like the following:\n",
    "\n",
    ".. code:: bash\n",
    "\n",
    "   Assignment\t\tw1\t\tw2\t\tw3\n",
    "\n",
    "   SER2H-SER2N-MET1CA\t\t8.226026\t\t117.193655\t\t55.477204\n",
    "   SER2H-SER2N-MET1CB\t\t8.224649\t\t117.184255\t\t32.845212\n",
    "   GLU3H-GLU3N-SER2CA\t\t8.003282\t\t119.841221\t\t58.603253\n",
    "   GLU3H-GLU3N-SER2CB\t\t8.002372\t\t119.827019\t\t64.067278\n",
    "   THR4H-THR4N-GLU3CA\t\t8.955568\t\t117.215237\t\t55.663902\n",
    "   THR4H-THR4N-GLU3CB\t\t8.955757\t\t117.206167\t\t32.96412"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Creating a `HNcoCACB` peak list file in `sparky`-like format and adding\n",
    "  noise values to `H` and `N` peak dimensions but not `C` peak dimension\n",
    "  from a single source of variance, i.e. 100% of peaks will have chemical\n",
    "  shift values adjusted using noise values from the defined random normal\n",
    "  distribution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "from nmrstarlib.noise import NoiseGenerator\n",
    "\n",
    "# create parameters dictionary for random normal distribution\n",
    "parameters = {\"H_loc\": [0], \"C_loc\": [None], \"N_loc\": [0],\n",
    "              \"H_scale\": [0.001], \"C_scale\": [None], \"N_scale\": [0.01]}\n",
    "\n",
    "# create random normal noise generator\n",
    "random_normal_noise_generator = NoiseGenerator(parameters)\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_HNcoCACB_ssv_HN.txt\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"sparky\",\n",
    "                                         spectrum_name=\"HNcoCACB\",\n",
    "                                         noise_generator=random_normal_noise_generator))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The generated `18569_HNcoCACB_ssv_HN.txt` peak list file should look like the following (note\n",
    "the chemical shift values differences in `H` and `N` dimensions for peaks that\n",
    "belong to the same spin system):\n",
    "\n",
    ".. code:: bash\n",
    "\n",
    "   Assignment\t\tw1\t\tw2\t\tw3\n",
    "\n",
    "   SER2H-SER2N-MET1CA\t\t8.226085\t\t117.191527\t\t55.489\n",
    "   SER2H-SER2N-MET1CB\t\t8.224509\t\t117.204666\t\t32.848\n",
    "   GLU3H-GLU3N-SER2CA\t\t8.001657\t\t119.846806\t\t58.593\n",
    "   GLU3H-GLU3N-SER2CB\t\t8.003165\t\t119.8268\t\t64.057\n",
    "   THR4H-THR4N-GLU3CA\t\t8.956946\t\t117.209486\t\t55.651\n",
    "   THR4H-THR4N-GLU3CB\t\t8.955755\t\t117.209889\t\t32.952"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Creating a `HNcoCACB` peak list file in `sparky`-like format and adding\n",
    "  noise values to peak dimensions from two sources of variance, i.e.\n",
    "  chemical shift values will be adjusted using noise values\n",
    "  from two random normal distributions. In order to specify two sources\n",
    "  of variance, we need to provide how we want to split our peak list and\n",
    "  provide statistical distribution parameters for both distributions. Let's\n",
    "  say we want 70 % of peaks to have a smaller variance in `H` and `N` dimensions\n",
    "  and 30 % of peaks to have a larger variance in `H` and `N` dimensions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "from nmrstarlib.noise import NoiseGenerator\n",
    "\n",
    "# create parameters dictionary for random normal distribution\n",
    "parameters = {\"H_loc\": [0, 0], \"C_loc\": [None, None], \"N_loc\": [0, 0],\n",
    "              \"H_scale\": [0.001, 0.005], \"C_scale\": [None, None], \"N_scale\": [0.01, 0.05]}\n",
    "\n",
    "# create random normal noise generator\n",
    "random_normal_noise_generator = NoiseGenerator(parameters)\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_HNcoCACB_tsv_HN.txt\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"sparky\",\n",
    "                                         spectrum_name=\"HNcoCACB\",\n",
    "                                         plsplit=(70,30),\n",
    "                                         noise_generator=random_normal_noise_generator))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The generated `18569.txt` peak list file should look like the following (note\n",
    "the larger variance in the last four peaks especially in `N` dimension):\n",
    "\n",
    ".. code:: bash\n",
    "\n",
    "   Assignment\t\tw1\t\tw2\t\tw3\n",
    "\n",
    "   SER2H-SER2N-MET1CA\t\t8.223356\t\t117.208041\t\t55.489\n",
    "   SER2H-SER2N-MET1CB\t\t8.22532\t\t    117.184278\t\t32.848\n",
    "   GLU3H-GLU3N-SER2CA\t\t8.00271\t\t    119.847153\t\t58.593\n",
    "   GLU3H-GLU3N-SER2CB\t\t8.002822\t\t119.824752\t\t64.057\n",
    "   ...\n",
    "   GLU114H-GLU114N-LEU113CA\t\t7.614195\t\t118.672897\t\t56.14\n",
    "   GLU114H-GLU114N-LEU113CB\t\t7.628722\t\t118.565859\t\t43.249\n",
    "   GLY115H-GLY115N-GLU114CA\t\t7.583248\t\t113.45153\t\t57.005\n",
    "   GLY115H-GLY115N-GLU114CB\t\t7.596634\t\t113.472049\t\t30.079"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Creating simulated peak lists with variance drawn from other distribution types\n",
    "*******************************************************************************\n",
    "\n",
    "* It is also possible to generate the simulated peak lists using other\n",
    "  types of statistical distribution functions. For example, let's\n",
    "  simulate the peak list using noise values drawn from ``chisquare``\n",
    "  distribution for 5 degrees of freedom for `H` and `N` dimensions\n",
    "  from single source of variance."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "from nmrstarlib.noise import NoiseGenerator\n",
    "\n",
    "# create parameters dictionary for distribution\n",
    "parameters = {\"H_df\": [5], \"C_df\": [None], \"N_df\": [5]}\n",
    "\n",
    "# create chisquare noise generator\n",
    "chisquare_noise_generator = NoiseGenerator(parameters, distribution_name=\"chisquare\")\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_HNcoCACB_ssv_HN_chi2.txt\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"sparky\",\n",
    "                                         spectrum_name=\"HNcoCACB\",\n",
    "                                         noise_generator=chisquare_noise_generator))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "The generated `18569_HNcoCACB_ssv_HN_chi2.txt` peak list file should look like the following:\n",
    "\n",
    ".. code:: bash\n",
    "\n",
    "   Assignment\t\tw1\t\tw2\t\tw3\n",
    "\n",
    "   SER2H-SER2N-MET1CA\t\t12.50083\t\t127.197738\t\t55.489\n",
    "   SER2H-SER2N-MET1CB\t\t10.495158\t\t121.039655\t\t32.848\n",
    "   GLU3H-GLU3N-SER2CA\t\t15.597162\t\t124.603078\t\t58.593\n",
    "   GLU3H-GLU3N-SER2CB\t\t8.340404\t\t126.784481\t\t64.057\n",
    "   THR4H-THR4N-GLU3CA\t\t10.010804\t\t120.476893\t\t55.651\n",
    "   THR4H-THR4N-GLU3CB\t\t11.961498\t\t121.681636\t\t32.952"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Below is the list of all supported distribution functions along with their parameters\n",
    "  if the ``numpy`` library is not installed:\n",
    "\n",
    ".. code-block:: python\n",
    "\n",
    "   {\n",
    "       {\"function\": \"uniform\", \"parameters\": [\"low\", \"high\"]},\n",
    "       {\"function\": \"triangular\", \"parameters\": [\"left\", \"right\", \"mode\"]},\n",
    "       {\"function\": \"beta\", \"parameters\": [\"a\", \"b\"]},\n",
    "       {\"function\": \"exponential\", \"parameters\": [\"scale\"]},\n",
    "       {\"function\": \"gamma\", \"parameters\": [\"shape\", \"scale\"]},\n",
    "       {\"function\": \"gauss\", \"parameters\": [\"mu\", \"sigma\"]},\n",
    "       {\"function\": \"normal\", \"parameters\": [\"loc\", \"scale\"]},\n",
    "       {\"function\": \"lognormal\", \"parameters\": [\"mean\", \"sigma\"]},\n",
    "       {\"function\": \"vonmises\", \"parameters\": [\"mu\", \"kappa\"]},\n",
    "       {\"function\": \"pareto\", \"parameters\": [\"a\"]}\n",
    "   }\n",
    "\n",
    "* And the list of all supported distribution functions along with their parameters\n",
    "  if the ``numpy`` library is installed:\n",
    " \n",
    ".. code-block:: python\n",
    "\n",
    "   {\n",
    "       {\"function\": \"beta\", \"parameters\": [\"a\", \"b\"]},\n",
    "       {\"function\": \"binomial\", \"parameters\": [\"n\", \"p\"]},\n",
    "       {\"function\": \"chisquare\", \"parameters\": [\"df\"]},\n",
    "       {\"function\": \"exponential\", \"parameters\": [\"scale\"]},\n",
    "       {\"function\": \"f\", \"parameters\": [\"dfnum\", \"dfden\"]},\n",
    "       {\"function\": \"gamma\", \"parameters\": [\"shape\", \"scale\"]},\n",
    "       {\"function\": \"geometric\", \"parameters\": [\"p\"]},\n",
    "       {\"function\": \"gumbel\", \"parameters\": [\"loc\", \"scale\"]},\n",
    "       {\"function\": \"hypergeometric\", \"parameters\": [\"ngood\", \"nbad\", \"nsample\"]},\n",
    "       {\"function\": \"laplace\", \"parameters\": [\"loc\", \"scale\"]},\n",
    "       {\"function\": \"logistic\", \"parameters\": [\"loc\", \"scale\"]},\n",
    "       {\"function\": \"lognormal\", \"parameters\": [\"mean\", \"sigma\"]},\n",
    "       {\"function\": \"logseries\", \"parameters\": [\"p\"]},\n",
    "       {\"function\": \"negative_binomial\", \"parameters\": [\"n\", \"p\"]},\n",
    "       {\"function\": \"noncentral_chisquare\", \"parameters\": [\"df\", \"nonc\"]},\n",
    "       {\"function\": \"noncentral_f\", \"parameters\": [\"dfnum\", \"dfden\", \"nonc\"]},\n",
    "       {\"function\": \"normal\", \"parameters\": [\"loc\", \"scale\"]},\n",
    "       {\"function\": \"pareto\", \"parameters\": [\"a\"]},\n",
    "       {\"function\": \"poisson\", \"parameters\": [\"lam\"]},\n",
    "       {\"function\": \"power\", \"parameters\": [\"a\"]},\n",
    "       {\"function\": \"rayleigh\", \"parameters\": [\"scale\"]},\n",
    "       {\"function\": \"triangular\", \"parameters\": [\"left\", \"mode\", \"right\"]},\n",
    "       {\"function\": \"uniform\", \"parameters\": [\"low\", \"high\"]},\n",
    "       {\"function\": \"vonmises\", \"parameters\": [\"mu\", \"kappa\"]},\n",
    "       {\"function\": \"wald\", \"parameters\": [\"mean\", \"scale\"]},\n",
    "       {\"function\": \"weibull\", \"parameters\": [\"a\"]},\n",
    "       {\"function\": \"zipf\", \"parameters\": [\"a\"]}\n",
    "   }"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Spectrum description configuration file\n",
    "---------------------------------------\n",
    "\n",
    "Spectrum description configuration file (`spectrum_description.json`) contains\n",
    "descriptions for standard solution and solid-state NMR experiments.\n",
    "\n",
    "* List all available experiments:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nmrstarlib.nmrstarlib.list_spectrums()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* List all available spectrum descriptions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nmrstarlib.nmrstarlib.list_spectrum_descriptions()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* List specific spectrum descriptions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "nmrstarlib.nmrstarlib.list_spectrum_descriptions(\"HNcoCACB\", \"NCACX\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Adding a custom experiment description and simulating peak list based on it.\n",
    "  Custom spectrum description can be added in several ways:\n",
    "\n",
    "   1. Create additional json configuration with spectrum description and update\n",
    "      `SPECTRUM_DESCRIPTIONS` :py:class:`dict`. Content of `custom_spectrum_description.json`.\n",
    "   2. Define dictionary with new spectrum description and update\n",
    "      `SPECTRUM_DESCRIPTIONS` :py:class:`dict`."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "1. Create additional json configuration with spectrum description and updating\n",
    "   `SPECTRUM_DESCRIPTIONS` :py:class:`dict`. Content of `custom_spectrum_description.json`.\n",
    "\n",
    ".. code:: bash\n",
    "   \n",
    "   {\n",
    "       \"NCACX_custom\": {\n",
    "           \"Labels\": [\"N\", \"CA\", \"CX\"],\n",
    "           \"MinNumberPeaksPerSpinSystem\": 2,\n",
    "           \"PeakDescriptions\": [\n",
    "               {\"fraction\": 1, \"dimensions\": [\"N\", \"CA\", \"CO\"]},\n",
    "               {\"fraction\": 1, \"dimensions\": [\"N\", \"CA\", \"CA\"]},\n",
    "               {\"fraction\": 1, \"dimensions\": [\"N\", \"CA\", \"CB\"]}\n",
    "           ]\n",
    "       }\n",
    "   }"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "from nmrstarlib.noise import NoiseGenerator\n",
    "\n",
    "# update SPECTRUM_DESCRIPTIONS\n",
    "nmrstarlib.nmrstarlib.update_constants(spectrum_descriptions_cfg=\"path/to/custom_spectrum_description.json\")\n",
    "\n",
    "# create parameters dictionary for random normal distribution\n",
    "parameters = {\"H_loc\": [None, None], \"C_loc\": [0, 0], \"N_loc\": [0, 0],\n",
    "              \"H_scale\": [None, None], \"C_scale\": [0.01, 0.05], \"N_scale\": [0.01, 0.05]}\n",
    "\n",
    "# create random normal noise generator\n",
    "random_normal_noise_generator = NoiseGenerator(parameters)\n",
    "\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_NCACX_custom.txt\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"sparky\",\n",
    "                                         spectrum_name=\"NCACX_custom\",\n",
    "                                         plsplit=(70,30),\n",
    "                                         noise_generator=random_normal_noise_generator))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "2. Define dictionary with new spectrum description and update `SPECTRUM_DESCRIPTIONS` :py:class:`dict`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.converter import Converter\n",
    "from nmrstarlib.translator import StarFileToPeakList\n",
    "from nmrstarlib.noise import NoiseGenerator\n",
    "\n",
    "custom_experiment_type = {\n",
    "    \"NCACX_custom\": {\n",
    "        \"Labels\": [\"N\", \"CA\", \"CX\"],\n",
    "        \"MinNumberPeaksPerSpinSystem\": 2,\n",
    "        \"PeakDescriptions\": [\n",
    "            {\"fraction\": 1, \"dimensions\": [\"N\", \"CA\", \"CO\"]},\n",
    "            {\"fraction\": 1, \"dimensions\": [\"N\", \"CA\", \"CA\"]},\n",
    "            {\"fraction\": 1, \"dimensions\": [\"N\", \"CA\", \"CB\"]}\n",
    "        ]\n",
    "    }\n",
    "}\n",
    "\n",
    "# update SPECTRUM_DESCRIPTION\n",
    "nmrstarlib.nmrstarlib.SPECTRUM_DESCRIPTIONS.update(custom_experiment_type)\n",
    "\n",
    "# create parameters dictionary for random normal distribution\n",
    "parameters = {\"H_loc\": [0, 0], \"C_loc\": [None, None], \"N_loc\": [0, 0],\n",
    "              \"H_scale\": [0.001, 0.005], \"C_scale\": [None, None], \"N_scale\": [0.01, 0.05]}\n",
    "\n",
    "# create random normal noise generator\n",
    "random_normal_noise_generator = NoiseGenerator(parameters)\n",
    "\n",
    "# Using valid BMRB id to access file from URL: from_path=\"18569\"\n",
    "converter = Converter(StarFileToPeakList(from_path=\"18569\", to_path=\"out/18569_NCACX_custom.txt\",\n",
    "                                         from_format=\"nmrstar\", to_format=\"sparky\",\n",
    "                                         spectrum_name=\"NCACX_custom\",\n",
    "                                         plsplit=(70,30),\n",
    "                                         noise_generator=random_normal_noise_generator))\n",
    "converter.convert()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Visualizing chemical shifts values\n",
    "----------------------------------\n",
    "\n",
    "Chemical shifts values can be visualized using the :mod:`nmrstarlib.csviewer`\n",
    "Chemical Shifts Viewer module."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Visualize all available chemical shifts for all amino acids. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.csviewer import CSViewer\n",
    "\n",
    "csviewer = CSViewer(from_path=\"18569\", filename=\"out/18569_chem_shifts_all\", csview_format=\"png\")\n",
    "csviewer.csview(view=False)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ":mod:`nmrstarlib.csviewer` output example:\n",
    "\n",
    ".. image:: _static/images/18569_chem_shifts_all.png\n",
    "   :width: 110%\n",
    "   :align: center"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Visualize `CA`, `CB`, `CG`, and `CG2` chemical shifts for specific amino acids."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.csviewer import CSViewer\n",
    "\n",
    "csviewer = CSViewer(from_path=\"18569\", amino_acids=[\"GLU\", \"THR\"], atoms=[\"CA\", \"CB\", \"CG\", \"CG2\"],\n",
    "                    filename=\"out/18569_chem_shifts_SER_THR_CA_CB_CG_CG2\", csview_format=\"png\")\n",
    "csviewer.csview(view=False)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ":mod:`nmrstarlib.csviewer` output example:\n",
    "\n",
    ".. image:: _static/images/18569_chem_shifts_GLU_THR_CA_CB_CG_CG2.png\n",
    "   :width: 60%\n",
    "   :align: center"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Visualize specific atoms for specific amino acids."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nmrstarlib.csviewer import CSViewer\n",
    "\n",
    "csviewer = CSViewer(from_path=\"18569\", amino_acids_and_atoms={\"GLU\": [\"CA\", \"CB\"], \"THR\": [\"HA\", \"HB\"]},\n",
    "                    filename=\"out/18569_chem_shifts_GLU_CA_CB_THR_HA_HB\", csview_format=\"png\")\n",
    "csviewer.csview(view=False)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ":mod:`nmrstarlib.csviewer` output example:\n",
    "\n",
    ".. image:: _static/images/18569_chem_shifts_GLU_CA_CB_THR_HA_HB.png\n",
    "   :width: 45%\n",
    "   :align: center"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "Command Line Interface\n",
    "~~~~~~~~~~~~~~~~~~~~~~\n",
    "Command Line Interface functionality:\n",
    "   * Convert from the NMR-STAR file format into its equivalent JSON file format and vice versa.\n",
    "   * Create simulated peak list files using chemical shift and assignment information.\n",
    "   * Visualize assigned chemical shift values."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib --help"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "CLI Converting NMR-STAR files in bulk\n",
    "-------------------------------------\n",
    "\n",
    "CLI one-to-one file conversions\n",
    "*******************************\n",
    "\n",
    "* Convert from a local file in NMR-STAR format to a local file in JSON format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert bmr18569.str out/bmr18569.json \\\n",
    "          --from-format=nmrstar --to-format=json"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a local file in JSON format to a local file in NMR-STAR format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert bmr18569.json out/bmr18569.str \\\n",
    "          --from-format=json --to-format=nmrstar"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a compressed local file in NMR-STAR format to a compressed local file in JSON format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert bmr18569.str.gz out/bmr18569.json.gz \\\n",
    "          --from-format=nmrstar --to-format=json"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a compressed local file in JSON format to a compressed local file in NMR-STAR format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert bmr18569.json.gz out/bmr18569.str.gz \\\n",
    "          --from-format=json --to-format=nmrstar"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a uncompressed URL file in NMR-STAR format to a compressed local file in JSON format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert 18569 out/bmr18569.json.bz2 \\\n",
    "          --from-format=nmrstar --to-format=json"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note:: See :mod:`nmrstarlib.converter` for full list of available  \n",
    "          conversions."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "CLI many-to-many files conversions\n",
    "**********************************\n",
    "\n",
    "* Convert from a directory of files in NMR-STAR format to a directory\n",
    "  of files in JSON format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert starfiles_dir_nmrstar out/starfiles_dir_json \\\n",
    "          --from-format=nmrstar --to-format=json"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a directory of files in JSON format to a directory \n",
    "  of files in NMR-STAR format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert starfiles_dir_json out/starfiles_dir_nmrstar \\\n",
    "          --from-format=json --to-format=nmrstar"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a directory of files in NMR-STAR format to a zip \n",
    "  archive of files in JSON format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert starfiles_dir_nmrstar out/starfiles_json.zip \\\n",
    "          --from-format=nmrstar --to-format=json"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a compressed tar archive of files in JSON format to a \n",
    "  directory of files in NMR-STAR format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert starfiles_json.tar.gz out/starfiles_dir_nmrstar \\\n",
    "          --from-format=json --to-format=nmrstar"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Convert from a zip archive of files in NMR-STAR format to a \n",
    "  compressed tar archive of files in JSON format:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib convert starfiles_nmrstar.zip out/starfiles_json.tar.bz2 \\\n",
    "          --from-format=nmrstar --to-format=json"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note:: See :mod:`nmrstarlib.converter` for full list of available \n",
    "          conversions."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "CLI Creating simulated peak list files from NMR-STAR files in bulk\n",
    "------------------------------------------------------------------\n",
    "\n",
    "\n",
    "CLI one-to-one file simulations\n",
    "*******************************\n",
    "\n",
    "* Creating a zero-variance `HNcoCACB` peak list file in `sparky`-like \n",
    "  format from local NMR-STAR formatted file (`bmr18569.str`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate bmr18569.str out/18569_HNcoCACB.txt HNcoCACB \\\n",
    "          --from-format=nmrstar --to-format=sparky"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Creating a `HNcoCACB` peak list file in `sparky`-like format and adding\n",
    "  noise values to peak dimensions from a single source of variance, i.e.\n",
    "  100% of peaks will have chemical shift values adjusted using noise values\n",
    "  from the defined random normal distribution (note that we can use `18569` BMRB id\n",
    "  instead of local file):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate 18569 out/18569_HNcoCACB_ssv_HCN.txt HNcoCACB \\\n",
    "          --from-format=nmrstar --to-format=sparky \\\n",
    "          --H=0,0.001 --N=0,0.01 --C=0,0.01"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Creating a `HNcoCACB` peak list file in `sparky`-like format and adding\n",
    "  noise values to peak dimensions from a single source of variance, i.e.\n",
    "  100% of peaks will have chemical shift values adjusted using noise values\n",
    "  from the defined chisquare distribution for degrees of freedom equal to 5:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate 18569 out/18569_HNcoCACB_ssv_HCN_chi2.txt HNcoCACB \\\n",
    "          --from-format=nmrstar --to-format=sparky \\\n",
    "          --H=5 --N=5 --C=5 --distribution=chisquare"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Creating a `HNcoCACB` peak list file in `sparky`-like format and adding\n",
    "  noise values to `H` and `N` peak dimensions but not `C` peak dimension\n",
    "  from a single source of variance, i.e. 100% of peaks will have chemical\n",
    "  shift values adjusted using noise values from the defined random normal\n",
    "  distribution (note that we can use compressed `bmr18569.str.gz` file):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate bmr18569.str.gz out/18569_HNcoCACB_ssv_HN.txt HNcoCACB \\\n",
    "          --from-format=nmrstar --to-format=sparky \\\n",
    "          --H=0,0.001 --N=0,0.01"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Creating a `HNcoCACB` peak list file in `sparky`-like format and adding\n",
    "  noise values to peak dimensions from two sources of variance, i.e.\n",
    "  chemical shift values will be adjusted using noise values\n",
    "  from two random normal distributions. In order to specify two sources\n",
    "  of variance, we need to provide how we want to split our peak list and\n",
    "  provide statistical distribution parameters for both distributions. Let's\n",
    "  say we want 70 % of peaks to have a smaller variance in `H` and `N` dimensions\n",
    "  and 30 % of peaks to have a larger variance in `H` and `N` dimensions. Note\n",
    "  that values per split are separated by ``:`` and then parameters are separated\n",
    "  by ``,``."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate 18569 out/18569_HNcoCACB_tsv_HN.txt HNcoCACB \\\n",
    "          --from-format=nmrstar --to-format=sparky \\\n",
    "          --plsplit=70,30 --H=0:0,0.001:0.005 --N=0:0,0.01:0.05"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note:: See :mod:`nmrstarlib.converter` for full list of available one-to-one and many-to-many\n",
    "          input and output formats."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "CLI many-to-many files simulations\n",
    "**********************************\n",
    "\n",
    "* Simulate zero-variance `HNcoCACB` peak lists from a directory of NMR-STAR formatted files\n",
    "  to a directory of peak list files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate starfiles_dir_nmrstar out/peaklists_dir HNcoCACB \\\n",
    "          --from-format=nmrstar --to-format=sparky"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Simulate `HNcoCACB` peak lists from a directory of NMR-STAR formatted files\n",
    "  to a zip archive of peak list files, add random normal noise values to\n",
    "  `H` and `N` peak dimensions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate starfiles_dir_nmrstar out/peaklists.zip HNcoCACB \\\n",
    "          --from-format=nmrstar --to-format=sparky --H=0,0.001 --N=0,0.01"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Simulate `NCACX` peak lists from a directory of NMR-STAR formatted files\n",
    "  to a tar.gz archive of peak list files, add random normal noise values to\n",
    "  `C` and `N` peak dimensions using two sources of variance, 70 % of peaks\n",
    "  will have smaller variance, 30 % of peaks will have larger variance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib plsimulate starfiles_dir_nmrstar out/peaklists.tar.gz NCACX \\\n",
    "          --from-format=nmrstar --to-format=sparky --plsplit=70,30 \\\n",
    "          --C=0:0,0.01:0.05 --N=0:0,0.01:0.07"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. note:: See :mod:`nmrstarlib.converter` for full list of available one-to-one and many-to-many\n",
    "          input and output formats."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "CLI Visualizing chemical shift values\n",
    "-------------------------------------\n",
    "\n",
    "* Visualize chemical shift values for the entire sequence:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib csview 18569 --csview-outfile=out/18569_chem_shifts_all \\\n",
    "          --csview-format=png"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. image:: _static/images/18569_chem_shifts_all.png\n",
    "   :width: 110%\n",
    "   :align: center"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Visualize `CA`, `CB`, `CG`, and `CG2` chemical shift values for `GLU` and `THR` amino acid residues:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib csview 18569 --aa=GLU,THR --at=CA,CB,CG,CG2 \\\n",
    "          --csview-outfile=out/18569_chem_shifts_GLU_THR_CA_CB_CG_CG2 \\\n",
    "          --csview-format=png"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. image:: _static/images/18569_chem_shifts_GLU_THR_CA_CB_CG_CG2.png\n",
    "   :width: 60%\n",
    "   :align: center"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "* Visualize specific atoms for specific amino acids."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "! python3 -m nmrstarlib csview 18569 --aa-at=GLU-CA,CB:THR-HA,HB \\\n",
    "          --csview-outfile=out/18569_chem_shifts_GLU_CA_CB_THR_HA_HB \\\n",
    "          --csview-format=png"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ":mod:`nmrstarlib.csviewer` output example:\n",
    "\n",
    ".. image:: _static/images/18569_chem_shifts_GLU_CA_CB_THR_HA_HB.png\n",
    "   :width: 45%\n",
    "   :align: center"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "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.5.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
