\documentclass[../book.tex]{subfiles}
\graphicspath{{\subfix{.}}}
\begin{document}

\chapter{Generating Molecular Structures and Annotating Plots}
\label{03DrawMol}


\setcounter{section}{-1}  % Start subsections from 0

\input{prereqs/03DrawMol_prereqs}

\newpage
\section{Problem}
\setcounter{subsection}{-1}  % Start subsections from 0

You now have a plot of your titration that you could share with someone else.  The only problem is that you don't like how it is labeled.  For one thing, it has a legend, which you don't like because it brings attention away from the data. For another, there is no title.  While you could add one, you are also a proud chemist, who easily thinks in the symbolic language of chemistry: chemical structures.  Rather than writing a title that is something like "Titration of \ce{Ni[pz]2} with an Acid" you would rather draw out the chemical reaction and add this to the plot as an annotation.  And if you match the color of your structures to the lines in your plot, you don't need the legend anymore. If only you had a way to draw chemical structures...

You bring this up to \first who says, "Oh yeah! It turns out that there is a way to draw chemical structures in Python. 
If you want them to look beautiful, it will require a bit of work, but if you simply what a drawing, then it is pretty straightforward. 
Also, learning this will help illustrate a few other concepts in Python you should know about.  So why don't we go ahead and add the chemical reaction to your plot!"


\section{Solution}
\setcounter{subsection}{-1}  % Start subsections from 0

\subsection{Planning}
The rough outline for this workflow problem is rather straightforward.

\begin{enumerate}
    \item Use the same plot from Chapter \ref{02ManyPlots}. 

    \item Create drawings for the reactant and product, matching the colors to the structures to the colors you used in plotting the data. 

    \item Add the molecules to your plot, connected by a reaction arrow that indicates this is a titration (i.e., \ce{H+} is above the arrow).
\end{enumerate}
\First looks over this and agrees that this is a good basic plan.  And they note that you really are just trying to add functionality to code you already have, so you can just return to the plotting script you already have (Section \ref{ManyPlot:Code}) an add in new code (remembering to advance the version number as discussed in Section \ref{Keeping_track_of_changes_to_your_code_using_versioning_practices}). But, before you can implement it, you will need to understand a few more concepts. 


\subsection{Accessing items from dictionaries using keys}
\label{Accessing_items_from_dictionaries_using_keys}

``Last time, we we saw how to \textit{create} \cite{dictionaries}, using a set of \cite{key}/\cite{value} pairs, which could be created like so:"

\begin{pyin}
numbers = dict(Ben = 11, Chris = 3.14)
\end{pyin}
``Well, we can access the values from a dictionary by using the dictionary and supplying the key between square brackets."

\begin{pyin}
numbers["Ben"]
\end{pyin}
\begin{pyout}
11
\end{pyout}
``If we try to iterate through a dictionary on its own (for instance using a \citett{for} \cite{loop}), the keys will be passed to the loop variable one at a time:"\footnote{You might read online that dictionaries are \cite{unordered}, and so we cannot be guaranteed that we can iterate through them in the same order every time. However, since Python 3.7, dictionaries are ordered, and so we will iterate through the items in the same order each time. At the time of this writing, the most recent version of Python was 3.13.2}
\begin{lstlisting}
for k in numbers:
    print(k)
\end{lstlisting}
\begin{pyout}
Ben
\end{pyout}
\begin{pyout}
Chris
\end{pyout}
``Which we could use to access the values in a within a \lstinline{for} loop. Go ahead, change the code above to read \lstinline{print(numbers[k])}, and you will then print the values, rather than the keys."


% \subsection{Running code from other files using \lstinline{run_path()}}
% \label{Sec:N:03DrawMol:run_path}

% There are going to be times that you wish to re-use code.  For instance, in this chapter, we want the same figure that we had last chapter, so that we can add things to it. One way to do this is to copy and paste the code over, but this can lead to a number of problems. To name just one: if you change the code in one place, and not the other, then you now have 2 slightly different versions that you must keep track of, when you move between programs. This compounds as you copy and paste. 

% So, if you simply want one object from another code, a solution is to run the Python file that has your old code \textit{within} the new code. There are several ways to do so, but in this chapter we will use the \lstinline{runpy} library's \lstinline{run_path()} function. If you supply this function a path that points to a Python file, it will run that file, and then collect all the objects in that file's \ul{namespace} and return their variable names and values as key:value pairs in a dictionary. If you know the name of the variables you want to use, you can obtain them from this dictionary as we just illustrated directly above. 


\subsection{Describing chemical structures using SMILES}
\label{Describing_chemical_structures_using_SMILES}

``One reason that skeletal formulas are so useful is that people are visual creatures. We can look at a molecule and quickly identify if it is benzene, toluene, or a xylene. Computers are not (yet) visual creatures.  So we need to have a way to communicate to a computer how atoms are connected in a way that it can understand.  One way to do this is using \cite{SMILES} (\ul{S}implified \ul{M}olecular \ul{I}nput \ul{L}ine \ul{E}ntry \ul{S}ystem).\footnote{There are MANY different formats that computers use, and this is just one.  Other familiar ones are .pdb, .cdxl, .mol, .xyz, etc.} SMILES takes the form of a string of letters, numbers, and other symbols that specify what atoms are present, how they are connected to one another, and what charges they bear."

``If you want to try to either write your own SMILES or read a SMILES, then you can start learning by reading the Wikipedia page on them. However, there are also free online utilities that can help."\footnote{As a free resource, we recommend:\\https://www.cheminfo.org/flavor/malaria/Utilities/SMILES\_generator\_\_\_checker/index.html\\However, if you have access to commercial software, such as ChemDraw, they can also generate SMILES from structures, and vice versa. } Using them, you will find that toluene is Cc1ccccc1, while acetic acid is CC(=O)O, and acetate is CC(=O)[O-].



\subsection{Drawing molecules with RDKit}
\label{Drawing_molecules_with_RDKit}

``If you have the \cite{SMILES} for a molecule of interest, you are now ready to have Python draw it for you, using the RDKit \cite{library}.\footnote{Actually, you can also use things like CAS number, etc. But we are using SMILES so that you know how to draw things that may not yet be known.} Let's assume we want to draw acetate.  To do so, we can run the following code:"

\lstinputlisting[language = Python]{../../Distribution/Code by Chapter/Ch04 - Generating Molecular Structures and Annotating Plots/rdkitExample.py}

%\begin{mdframed}
%    At the time that this book was written, Rdkit was not yet availible for Windows machines running on arm64 processors (e.g., Snapdragon, etc.). So, if you are using such a machine, you would not be able to execute the portions of code that rely on the Rdkit library.  Thus, your options would be to skip this part, or use a different computer. 
%\end{mdframed}

You run this code in the Spyder IDE, and it outputs the following image to the Python console. \footnote{For some people, the image will not output to the console.  You can open the image in a new window by using \lstinline{Draw.ShowMol(acetate_mol)} instead.}

\begin{figure}[h]
    \centering
    \includegraphics[width = 0.66in]{ChapNarrative/03DrawMol/figures/acetate.png}

    \caption{Skeletal formula for acetate. This was drawn programmatically using the RDKit \cite{library} in Python. Using this library, one can specify the \cite{SMILES} \cite{string} (among many options) for the molecule, which is \texttt{CC(=O)[O-]} for acetate. }
    \label{fig:DrawMol:Acetate}
\end{figure}
``What happened here is we made an RDKit \lstinline{mol} \cite{object} (the main way that molecules are described in RDKit) from a SMILES string.  Then, we use the \lstinline{ShowMol()} \cite{method} of the \lstinline{Draw} \cite{class} to generate the image.\footnote{If you would like to save a file, instead, see Problem 1 in Chapter 14.}  It is so simple!"\\
\begin{wrapfigure}{r}{0.5\textwidth}
    \begin{mdframed}
        \textbf{Why RDKit?}
        
        \noindent A quick web search will turn up many different libraries for cheminformatics, and many of these can draw molecules. However, we felt that RDKit was the library that provided the quickest access to this capability.  If you become interested in this area, check out the ACS InFocus book ``Python for Chemists," which focuses on cheminformatics.
    \end{mdframed}
\end{wrapfigure}

``This is a fine drawing, but RDKit, by default, will color atoms and bonds associated with them. This can look a bit busy. If you want to control the colors of the bonds, or change other aspects of the molecule (bond lengths, widths, other colors, etc.) things become even more complex.  A more complete example will be shown in the final code for this chapter, but to understand that, we have to understand tuples and color specification in Python. Let's talk about that." 


\subsection{Using tuples to create unchangeable lists}
\label{Using_tuples_to_create_unchangeable_lists}

``So far we have seen a few types of \cite{collection}s: \cite{Numpy_array}s, \cite{dictionaries}, \cite{string}s, and \cite{list}s. Now we will encounter another: the \cite{tuple}.  A tuple is created by placing elements between parentheses, separated by comments."

\begin{pyin}
tup = (2, "me", False)
\end{pyin}
``You can \cite{slice} a tuple, which means you can also access elements by \cite{index}:"

\begin{pyin}
tup[1]
\end{pyin}
\begin{pyout}
'me'
\end{pyout}
``You can see that tuples can hold another other \cite{object}s, and so it behaves a bit like a list.  However, there is one important difference: tuples cannot be altered, meaning that you cannot change their elements, add elements, or sort them. This is a property known as \cite{immutability}. Trying to alter a typle will generate an error."

\begin{pyin}
tup[1] = "you"
\end{pyin}
\begin{multiout}
Traceback (most recent call last):
  File "<pyshell#59>", line 1, in <module>
    tup[1] = "you"
TypeError: 'tuple' object does not support item assignment
\end{multiout}
``It might seem strange to create a data object you cannot change, but there are  few reasons to do so.  For one, it makes the data a bit more secure---you cannot accidentally change the values in a tuple.  For another, they can be more \cite{memory} efficient and faster to use.  However, I do not find these advantages to be compelling reasons to use tuples over lists most of the time.  Unless I'm forced to use tuples, I will just use lists. Specifying colors within RDKit is one example that requires tuples, which is why we are supplying them here."


\subsection{Specifying colors using the rgb standard}
\label{Specifying_colors_using_the_rgb_standard}

``Now, we need to learn some nuts and bolts of color so that you can format the structures and their positions in the figure the way you want.  So far, we have only needed to use color in our Plotly figures, and we have seen that Plotly has some named colors it knows about (e.g., "darkcyan" and "darkred").\footnote{For a complete list, see the Plotly documentation online.} But there are times that you will want to use a color that is not named.  Or you may need to change the color of an object that doesn't use named colors.  For instance, RDKit does not have named colors. In these cases, you need to specify colors in a way that a computer can recognize."

``One common way to do this is with so-called rgb colors (red-green-blue), which specify the intensity of three primary colors (red, green, and blue) we want. This is done using a \cite{tuple} of these values. However, there are two common approaches to specifying the intensity we want for each primary color---and we will see both of them in our code below. In both specifications, the minimum amount of light you can have is 0.  In one, the maximum amount of light is 1, and we specify color changes as any number between 0 and 1. In the other, the maximum value it is 255, and we specify color changes using any integer between 0 and 255."\footnote{The reason for 255 is color choices are digital, not continuous, so the 0--255 range in integers actually better reflects how a computer works ($2^8$ values). }

``In the latter system, pure red is (255, 0, 0), pure blue is (0, 0, 255), magenta is (255, 0, 255), and so on.  We can convert to the other system by dividing each number in the list by 255, which is how we will proceed in our code below."\footnote{For more information on color, see Chapter \ref{ch:plotly}.} 

``But there is even one more color specification worth knowing about here: the so-called rgba system.  This system provides 4 intensities, where the first three are the amount of red, green, and blue light, while the 4th value is known as the alpha-channel, and controls how transparent the color is. If this is given a value of 0, then the color is completely transparent, while a maximum value (either 1 or 255), means the color is completely opaque. When working with Plotly, there is a small wrinkle: the rbg values are all between 0 and 255, but the `a' value is between 0 and 1.  This is something worth remembering."


\subsection{Decoding data from binary files}
\label{Decoding_data_from_binary_files}

``Text and images are not the native language of a computer. Instead, 0s and 1s are. Thus, from the computer's perspective, data that is represented by 0s and 1s (i.e., in \cite{binary_format}) is more efficient to store, faster to process, and more accurate. For this reason, it is often desirable to move between text-based representations of data to so-called binary formats. The base64 library accomplishes this for one particular kind of binary file, using so-called \cite{base64_encoding}. We are going to use this to embed an image in a Plotly figure.  The Plotly library can use \cite{scalable_vector_graphic}s, but the graphics must come in as binary information, which we will accomplish using the base64 library."


\subsection{Adding images to Plotly figures}
\label{Adding_images_to_Plotly_figures}

``Okay, so we know how to represent images, but how do we add them to figures?  The easiest way is to use the \lstinline{add_layout_image()} \cite{method} of a Plotly Figure object. To do so, we need to specify the image source, which can be either a bitmap file on your computer, a \cite{uri_binary_stream} (for instance, for an svg image), or a URL (web address). In addition, we can specify other information, like the position, size, etc. This is all explained in detail in the online Plotly documentation and partially explored in Chapter \ref{ch:plotly}." 



\subsection{Adding annotations to Plotly figures}
\label{Adding_annotations_to_Plotly_figures}

``Annotations can be a great way to add clarifying elements to your plots. We can add annotations, like arrows, lines, shapes, and text to a Plotly fFgure object using the \lstinline{add_annotation()} \cite{method}. The simplest use case is to provide the text label you want using the \lstinline{text} \cite{keyword_argument} for the function, and to specify the location on the plot using the \lstinline{x} and \lstinline{y} keyword arguments. The default behavior is to put this text on the figure and draw an arrow at the location provided, though we can remove the arrowhead (i.e., draw a line), change alignment of text, change how positioning is handled, and much more."\footnote{The code provided at the end of the chapter demonstrates what we feel will be the most common changes to annotations.   Again, this is explained in detail in the online Plotly documentation and partially explored in Chapter \ref{ch:plotly}.}

% HTML in plotly
\subsection{Formatting text in Plotly using HTML tags}
\label{Formatting_text_in_Plotly_using_HTML_tags}

As we learn to do more and more analysis automatically, we are going to want to automatically generate annotations in Plotly that look like a final product.  That way, we won't have to further edit the plots to make them look nice for presentations or publications.  Plotly originated as the plotting library for the Javascript language, which is the backbone of many of the interesting behaviors on webpages. Thus, the `native' way in which we format text in Plotly is through HTML tags.  \cite{HTML} stands for hypertext markup language, and is the standard for coding webpages.  It is built around tags that surround textual elements and specify how to display them. For instance, if you wanted to create a superscript, we place the text to be superscripted between \lstinline{<sup>} and \lstinline{</sup>} tags---these are called the opening and closing tags.  Similarly, subscripts are placed between \lstinline{<sub>} and \lstinline{</sub>} tags.  

\begin{mdframed}
    \textbf{Learning about HTML}
    
    \noindent HTML is a versatile language for displaying information in web browsers and is used heavily for a wide array of Python tools.  A complete discussion of HTML is beyond the scope of this book, but many resources exist online to teach yourself to use HTML.  One good place to start is \href{http://www.w3schools.com}{http://www.w3schools.com}. 
\end{mdframed}

``There are also instances when you don't need both open and closing tags. For instance, if you want to simply introduce a line break (to start a new line) you can use \lstinline{<br>} and no closing tag is needed."\footnote{To enter a character that is not on your keyboard, see Section \ref{Generating_symbols_that_aren't_on_your_keyboard_using_codechembook.symbols}.}

%Finally, if you want to enter a character that you don't have on your keyboard, you can use \cite{unicode} designations. These are strings of numbers and letters that are used to identify each \cite{glyph} in text. For instance, if you wanted to write the $\pm$ symbol, you can enter \lstinline{\u00b1}. If you want complete lists of unicode characters, you can search the web for them, or go to the companion website for this book: 

\subsection{Producing HTML-formatted text quickly using \texttt{codechembook.symbols}}
\label{Producing_HTML-formatted_text_quickly_using_codechembook.symbols}

While it is true that one can always directly use the \cite{HTML} formatting, as introduced above, this can be a bit frustrating.  In keeping with the theme to try to reduce frustration through programming, the \lstinline{codechembook} \cite{library} contains \cite{function}s that will format things in HTML code for you. For instance, rather than using \lstinline{<sup>text<\sup>} to place text in superscript, you can import \lstinline{codechembook.symbols.typesettingHTML.textsup()}, providing the text you want to have in superscript as an argument to this function. This function returns the properly encoded HTML, and we will see it used in the code at the end of this chapter. 
Right now, this probably looks longer to type out, but if you use \lstinline{from codechembook.symbols.typesettingHTML import textsup}, you can have direct access to this function, and this will save you time when you have multiple superscripts to use.  Of course, you can always decide directly use the HTML. 




\subsection{Generating sequences of numbers using \texttt{range()}}
\label{Generating_sequences_of_numbers_using_range}

``There are going to be many times that you want to make a series of numbers in numerical order. They can easily be generated using the \lstinline{range} \cite{data_type}.  Range \cite{object}s are created using the \lstinline{range()} \cite{function}, by providing between 1 and 3 positional arguments. The first \cite{argument} provides the starting number (\cite{inclusive}), the second argument provides the ending number (\cite{exclusive}), and the third number provides the step size.  If you leave out the last argument, the default step size is 1. Thus, if you wanted numbers between 1 and 10, you could use:"

\begin{pyin}
one_to_ten = range(1, 11)
\end{pyin}
``This doesn't produce a \cite{list}, because \lstinline{range} is its \textit{own} data type.  You can see this by printing the \cite{variable}."

\begin{pyin}
print(one_to_ten)
\end{pyin}
\begin{pyout}
range(1, 11)
\end{pyout}
``Instead of producing a list of numbers, the \lstinline{range} object is a \cite{generator}, which means it is an \cite{object} that contains instructions for generating these numbers,\footnote{Perhaps when generating the numbers from 1 to 10 the advantages of this approach is not clear.  But imagine wanting to generate the numbers from 1 to a trillion.   Clearly the instructions for doing so will take less memory than the actual list.} and we can access these instructions... for instance in a \lstinline{for} \cite{loop}."
\begin{lstlisting}
one_to_eleven = range(1, 11)
for num in one_to_ten:
    print(num)
\end{lstlisting}
Running this code prints out the numbers from 1 to 10, and you can see how this could be a convenient way to get sequences of numbers without having to type them out explicitly. 


%zip
\subsection{Synchronizing iteration through multiple collections using \texttt{zip()}}
\label{Synchronizing_iteration_through_multiple_collections_using_zip}

``There will be many times that you have multiple \cite{collection}s of \cite{object}s (e.e., \cite{list}s) and you wish to iterate through all of them in a single \citett{for} \cite{loop}.  For instance, imagine you had a list of numbers = [1, 2, 3] and a list of names = ["one", "two", "three"].  You might like to loop through both of these lists so that you can make a statement that <number> is <name>.  There are a few ways to accomplish this.  In this chapter we will show one, the \cite{function} 
\lstinline{zip()}."\footnote{In the next chapter we will show a different approach: using \lstinline{enumerate()} and \acite{indices}. Both ways have value, which is why we will teach both.}
\begin{lstlisting}
numbers = [1, 2, 3]
names = ["one", "two", "three"]

for number, name in zip(numbers, names):
    print(number, " is ", name)
\end{lstlisting}
This produces the following output:
\begin{multiout}
    1 is one
    2 is two
    3 is three
\end{multiout}
``Basically, \lstinline{zip()} will accept take any number of \cite{iterable} \cite{object}s (e.g., \cite{list}s or \cite{Numpy_array}s) as \cite{argument}s.  These objects must be exactly the same length, or you will get an error. When using \lstinline{zip()}, the \lstinline{for} loop iterates through the indices and returns a tuple comprised of values taken from the corresponding index from each list. This tuple can be unpacked to the variables given before \citett{in}. The end result is we have a variable for each list we gave, which will get a value equal to one of the items in each list as we go through the lists. This is a straightforward way to ensure we synchronize going through several lists at the same time."

% Functions
\subsection{Specifying the result of function evaluation using the \texttt{return} keyword}
\label{Specifying_the_result_of_function_evaluation_using_the_return_keyword}

``During our first lunch, we saw that it can be very helpful to write your own \cite{function}s.\footnote{Section \ref{Avoiding_repetitive_typing_by_making_your_own_functions}} In that example, we had the function directly produce our final desired result.  However, we often want to take the results of a function and use it in other places in our code.  To do this, we can use the \citett{return} \cite{keyword}, placing any values you want passed back from the function on the same line after this \cite{keyword}."

``Let's make a simple example: imagine you dropped a ball, and wanted to know its velocity at any time.  We know the equation for this is simple: $v = 9.8t^2$.  If we define a function that we could \cite{call} to return the  the velocity of the ball, we would do the following:" 

\begin{lstlisting}
def velocity_at_time(time):
    '''
    A function to find the velocity of a dropped object at a given time.

    Required Params:
    time (float): the time that has elapsed since the drop
    
    Returns:
    v (float): the velocity at that time
    '''
    v = 9.8 * time**2
    return v

v1 = velocity_at_time(2)
print(v1)
print(velocity_at_time(3))
\end{lstlisting}
Running this code gives two outputs on different lines: 39.2 and 88.2.  \First explains, ``The returned values were generated \textit{inside} the function and then passed back to code outside the function for later use. You can also see that we can either assign the returned value to a variable for later use (line 14), or use the returned value directly (line 16). When using the return keyword, the definition of the function still ends when you end the indentation \cite{block}, not necessarily where the return statement shows up."  


``One last thing,'' \first says. `` You may have noticed a large \cite{comment} directly after the line with the \lstinline{def} keyword and the rest of the function. This is a multi-line comment explains the workings of the function and is known as a \cite{docstring}, and it is very powerful. Let's talk about that." 

\subsection{Describing how to use your functions in docstrings}
\label{Describing_how_to_use_your_functions_in_docstrings}

``\acite{Docstring}s are \cite{string} \cite{literal}s that are used to document \cite{function}s, \cite{method}s, \cite{class}es, and \cite{module}s. They are enclosed in triple quotes (\lstinline{"""} or \lstinline{'''}) and are placed immediately after the function or method definition. When a function’s docstring is defined, it can be accessed via the \lstinline{__doc__} \cite{attribute} of the function. Some IDEs (like Spyder), will give you a pop-up that displays the docstring. Finally, Python provides a built-in \lstinline{help()} function. When you provide a function as the argument, this will return the docstring.\footnote{See Section \ref{Accessing_capabilities_beyond_basic_math_using_functions}}   A well-written docstring enhances code readability and maintainability by clearly explaining the purpose and usage of the function."

``Docstrings should help a programmer to understand what the function does, what arguments it accepts, and what it returns.  There are many different standard formats for docstrings, but typically they include
\begin{enumerate}
    \item A one-line description of the purpose of the function.
    \item The types of \cite{argument}s (also called \cite{parameter}s),\footnote{For disambiguation on the difference between arguments and parameters, refer to the technical chapter on functions.} the \cite{data_type}s that can be passed to them, and a one-line description of their purpose.  %Positional arguments should appear in the same order as they are required by the function definition.  Keyword arguments should give the correct spelling of the keyword.
    \item Value(s) \cite{return}ed, their \cite{data_type}s, and a one-line description of what is contained in them. If you are not going to use a return \cite{statement}, then it is a good idea to explicitly state this in the docstring. 
\end{enumerate}
It is good practice to always make a docstring for a function.  You may think that it slows you down, but you will save time in the long run as you reuse this function again and again."

\begin{mdframed}
    \textbf{Formatting docstrings.}
    
    \noindent The formats that you will see for docstrings are only a few examples of how people structure them. The primary thing to focus on is clear and easy to read documentation.  We roughly follow the Google style guide for docstrings, as this is the style that is automatically generated in Spyder, if you type \lstinline{'''} after a function definition line. But you can also consider using the Numpy style guide for docstrings, as it is also widely used.  
\end{mdframed}

%% start describing new bits

%\medskip
\First smiles and says, ``We know enough now to solve your problem.  We just need to tack on a bit more code to the end of the plotting script you just made (Section \ref{ManyPlot:Code}), so let's just focus on the new code.  We could place all this new code just \textit{before} \lstinline{titration_series.show("png+browser")} on line \#46. So lets do it!''



\section{Code}
\setcounter{subsection}{-1}  % Start subsections from 0

\begin{figure}[H]
    \centering
    \includegraphics[]{ChapNarrative/03DrawMol/figures/FlowChartCh4.pdf}
    \caption{Flowchart for adding a skeletal formula to our Plotly figure of UV-vis spectra.}
    \label{fig:DrawMol:ActionDiagram}
\end{figure}

% Insert code
Since you are just going to modify some code you already have you also update the \cite{docstring} at the top of the script to track the changes and the version numbers:

\lstinputlisting[language=Python, firstline = 1, lastline = 7]{../../Distribution/Code by Chapter/Ch04 - Generating Molecular Structures and Annotating Plots/PlotTitrationSpectraWithStructures.py}

You then go down to the line just after \lstinline{titration_series.update_yaxes(title = "absorbance", range = [0, 4.5])} in the script (what used to be line 45, but is now line 46 because of the new additional line about the new version in the docstring). You enter a blank line, and then start typing new code on line 48:

\lstinputlisting[language=Python, firstline=48, firstnumber=48]{../../Distribution/Code by Chapter/Ch04 - Generating Molecular Structures and Annotating Plots/PlotTitrationSpectraWithStructures.py}

Running the new script the same way as for your previous plotting script,\footnote{See Chapter \ref{02ManyPlots}.} you get the following output:

\begin{figure}
    \centering
    \includegraphics[width = 5in]{./figures/titration.png}
    \caption{A plot of a series of UV-visible spectra from a titration experiment, annotated with skeletal formulas diagramming the chemical change and labeling the spectra. This was enabled by being able to represent molecules using RDKit and learning how to add annotations in Plotly.}
    \label{fig:DrawMol:AnnotatedSpectra}
\end{figure}

\subsection{Line-by-line explanation}
\begin{footnotesize}
\textbf{Lines}: \textbf{Explanation}
\begin{itemize}
    \item [1--5:] Import libraries we will want to use.  The \lstinline{rdkit} imports are needed to produce the desired drawing of our molecule, while \lstinline{base64} is needed to encode the drawing for use in Plotly. We also import the \lstinline{textsup()} function from the codechembook library, which helps us give Plotly the HTML formatting it needs for superscripts. 

    Even though we are going to be working with a Plotly Figure object, we do not need to import Plotly, because we are simply going to add this code to the code from last chapter, which already imported the parts of Plotly we need. If you wanted to, you could still include the import of \lstinline{make_subplots()}---doing so is not a problem (it will not be loaded twice), it is just not needed. 

    \item [7--47:] This is the code from the previous chapter.

    \item [48--52:] Import the libraries needed for drawing the molecular structure, handling the image data, and typesetting HTML.
    
    \item [54--87]: We will define a function that will produce the desired molecular drawing from \lstinline{rdkit}, formatted correctly for inclusion within a Plotly Figure object. Though we could just include this code directly in the \lstinline{for} loop defined later (line 51), the use of a function helps us separate out the generation of the figure.  This kind of compartmentalization of code can help with readability, as it separates out the code by task. 

    \begin{itemize}
        \item [54:] Start with the definition of the function, with the \cite{parameters} that are expected. We are going to need a SMILES string, a color for the molecule, how wide to make the drawing, and how tall to make the drawing.  These are captured by the arguments \lstinline{smiles}, \lstinline{color}, \lstinline{bonds_wide}, and \lstinline{bonds_tall}, respectively. They will all be required.
        
        \item[55--65:] The docstring for the function.  This explains the purpose of the function, what the parameters are, and what the function will return. The parameters are defined by giving the name of the parameter, followed by the \cite{data_type} that is expected. Then there is a terse description. The return does not have a name, since we don't know what it will be called outside the function, but does have the data type and a terse description.

        \item [68:] Using the \lstinline{Chem.MolFromSmiles()} function, we produce a RDKit molecule \cite{object}, which we assign to a variable \lstinline{mol}. This creates the information that RDKit will need to produce the bonds and atom labels that form the drawing. We specify the molecule is using a SMILES string held within the variable \lstinline{smiles}.

        \item [71 \& 72:] On these two lines we add entries to a \cite{dictionary} that RDKit will use to specify colors of atoms and bonds.  Essentially, this dictionary contains \cite{key}:\cite{value} pairs that are <atomic number>:<color>. This dictionary is an attribute of the DrawingOptions object (see below) in RDKit, and when we tell RDKit to use this dictionary, for each atom, it will look at this dictionary to see what color that atom should be---identifying the atom by its atomic number.        

        We are going to draw a molecule so that all bonds and atoms are the same color. To ensure we have the same color for all atoms, we will simply create entries for all atomic numbers (from 1 to 118).  We use a \lstinline{for} loop and iterate through a \lstinline{range} object.  For each entry, we use the atomic number as a key and assign the value as the appropriate color, using the variable `color.' Thus, we have the color designated for any atom we could possibly be using. 

        \item [75:] We create an RDKit \lstinline{Drawer} object that will actually generate the data that specifies the scalable vector graphic (svg) and assign this object to the variable ``\lstinline{drawe}r''.  When doing this we can tell it how wide and how tall we want the drawing to be.  This is done in units of pixels. There is a default size for font, so we want to make sure the drawing is large enough for the heteroatom labels and the bonds to show when the labels use this font size. We have found that thinking in terms of the number of bonds moving horizontally or vertically and then scaling that number by a factor of 50$\times$ produces reasonable results. You can change this scaling if you like, and see if you prefer the output when the figure is scaled differently.  

        \item [76:] We tell the drawer object to use the dictionary we created of all atoms colors. 

        \item [77:] We set the background color for the drawing.  Here, there are 4 numbers provided. These are the \cite{rgb}a values.  'a' stands for "alpha" and controls how opaque the color is.  By setting it to 0, the background will be completely transparent, which just makes it a bit easier to use the image as an annotation, since you don't need to worry about the image overlapping with any other aspects of the plot. 

        \item [80 \& 81:] Start drawing the molecule, and then finish the drawing. At this point, we don't need to worry about anything else, other than both of these are needed to get the final molecule.

        \item [84:] The drawer object contains \textit{instructions} for drawing in text form.  Here we get this text and then remove the label "svg" from it, by replacing this bit with an empty string (''). This is needed before we encode the instructions to base64, simply because of how the base64 library works. 

        \item [85:] Encode the svg text into base64 uri, as this is needed to add to a Plotly Figure object.  We assign this to a variable, and this variable can be used with Plotly to add a figure to a plot.  Don't worry too much about the details of what this line is doing---this is just boilerplate that we have to do.

        \item[87:] Using the \lstinline{return} keyword, we tell the function to \cite{return} the value of the base64 uri.  
        
        This completes the function.  We will move on to the rest of the script, where we will  call the function from inside a \lstinline{for} loop.
    \end{itemize}

    \item [90 \& 91:] Provide the SMILES strings for the base and acid forms of the compound that was titrated. Save them as a variable for later use. 

    \item [94 \& 95:] We wish to match the colors of drawing we will make to the traces on our plot, so we need to define what they are.  Here we have colors that match dark cyan and dark red from Plotly, specified in the rgb format, with values that range from 0 to 1. These will ultimately be used with Rdkit to set the colors. If you ever need to find out what the rgb values are for named colors, you can look in the Plotly documentation, or use a color-picker tool to determine the rgb of the color. 

    \item [98--109:] We are now ready to add the drawing of both the base and acid forms of our molecule (the SMILES of which were given in Lines 43 and 44).  We will need to perform similar operations for both, but color them differently and place them in different places on the final plot, so we begin by using \lstinline{zip()} function so that we can iterate through the SMILES strings, colors, and positions together. We provide these lists on lines 52--54, where we end with the the \lstinline{:} character that specifies that we are moving into the \lstinline{for} loop. The SMILES strings are assigned to the variable \lstinline{species}, the colors to the variable \lstinline{color}, and the positions to the variable \lstinline{positions}. 
    \begin{itemize}

        \item [104--109:] We call the \lstinline{add_layout_image()} method of the Plotly Figure object to add an image to the plot. We specify how this is added, using a \cite{dictionary}. Here we will ultimately add two images, one for each iteration of the \lstinline{for} loop.
        \begin{itemize}
            \item [105:] The value for the \lstinline{source} needs to be the  image to be embedded, and here we will provide the  base64 encoded uri for the image. Since this is also what the function we wrote above returns, we can simply call the function, specifying the species, color, and width and height for the image. The returned object will then be assigned as the value associated with the \lstinline{source} keyword. 

            \item [106:] The values for the \lstinline{xref} and \lstinline{yref} keys specify how the $x$ and $y$ values are referenced.  That is, do they use the values on the axes, or relative to the `paper' (plot area), etc. We will use the actual $x$ and $y$ coordinates. 

            \item [107:] The values for the \lstinline{x} and \lstinline{y} keys provide the coordinates at which to place the image. We use a common $y$-value, but the position variable from the for loop for the $x$. This will result in both images being placed at the same vertical position, but separated horizontally (and placed above the position of the band we are interested).  

            \item [108:] The values for the \lstinline{xanchor} and \lstinline{yanchor} keys specify the alignment for the image.  We will center this horizontally and align at the top, vertically. 

            \item [109] The values for the \lstinline{sizex} and \lstinline{sizey} keys specify the maximum width and height of the image being drawn, in the same units as the axes. You will note these are different from those that were passed to our function, because those were used to determine the size of the image generated by Rdkit, while this is the size of the images when added to Plotly. The image is sized according to the $x$ and $y$ coordinates (because we specified \lstinline{xref="x", yref="y"} on line 159), so this will be 200 nm wide and 1 absorbance unit tall on the plot. So the image returned is resized when added to Plotly. Because we used an svg, the image can be resized without a loss in resolution and this will produce a nice looking image. 
            
            We also provide the closing parentheses needed.  The first closes the dictionary, while the second closes the \lstinline{add_layout_image()} method. 
        \end{itemize}
    \end{itemize}

    \item [112--116:] Using the \lstinline{add_annotation()} method of the Plotly Figure object we add an annotation to the plot. We also specify the details using a dictionary.  Here, we are going to draw an arrow between the two images, to symbolize the chemical reaction. 
    \begin{itemize}
        \item [113:] The values for the \lstinline{ax} and \lstinline{ay} keys provide the coordinate of the \textit{beginning} of the arrow. 

        \item[114:] Thee values for the \lstinline{x} and \lstinline{y} keys provide the coordinate for the \textit{end} of the arrow. 

        \item [115:] The values for the \lstinline{axref}, \lstinline{ayref}, \lstinline{xref}, \lstinline{yref} keys provide the type of reference for the coordinates of the beginning and end of the arrow, respectively. Again, we will use the coordinates of the $x$ and $y$ axes.

        \item [116] We want an arrow, so we tell Plotly to show it (strictly speaking, this is not needed, since the default option is to show the arrow, but we write this out in order to make it very clear we have an arrow.  Sometimes it can be nice to be a bit more verbose in order to make code more readable). We also specify the size of the head and the width of the line, both in pixels, and we specify the color of the arrow. Since this method is in the Plotly library, we can use a named color, in this case \lstinline{grey}. Finally, we close both the dictionary and the \lstinline{add_annotation()} method.
    \end{itemize}

    \item [119--124:] We repeat the above annotation process; now \textit{without} an arrow, but with text that specifies we have \ce{H+}. This is nearly identical to above, however, there are a few differences:
    \begin{itemize}
        \item [120:] We provide text that will be used as the annotation and also provide a color and size for this font. Note that we need to use HTML code to specify a superscript for the `+' symbol, and we use the \lstinline{textsup()} function from \lstinline{codechembook} to do this for us.

        \item [121:] We specify the reference point for the coordinates specifying the annotation position. By setting these references to \lstinline{x} and \lstinline{y}, the positions will be with respect to the axes scales. 
        
        \item[122:] We next set the position of the annotation by specifying the $x$ and $y$ values at which we want the annotation to appear.
        
        \item [123:] We set the alignment of the text with respect to the position of the annotation using the \lstinline{xanchor} and \lstinline{yanchor} keyword arguments.  In this case, we have it horizontally aligned to the center and vertically aligned at the bottom.

        \item [124:] By default, Plotly will include an 'arrow' (actually, just a line), and so we have to set \lstinline{showarrow} to \lstinline{False} in order to avoid this. 
    \end{itemize}

    \item [127:] Because we are going to have color-coded structures, we don't need a legend anymore.  So, we update the Plotly traces to not show a legend using the \lstinline{update_traces()} method of the Plotly figure.   This applies the specified changes to \textit{all} traces in the figure, unless we specify otherwise. We could have done this by only updating the last two traces (which were the only two left in the legend), by calling this function twice, once for each trace. But since \textit{none} of the traces need a legend anymore, this usage requires fewer lines of code. 

    \item [130 \& 131:] These are the final two lines of the code from the last chapter to output the plot---now containing our molecular structures annotated on it.
    
\end{itemize}
\end{footnotesize}
\First then says "I know this was a lot, but you don't always need to go through all of this.  If you are ok with the default settings RDKit is actually pretty straightforward to use.  Now you know how to use more of its functionality. It is a good thing to be a chemist and know how to draw chemical structures."

\hrule
\input{Exercises/Chapter 04 Using Python to draw molecules and add them to plots}
\hrule

%\include{Exercises/Chapter 04 Using Python to draw molecules and add them to plots}

\end{document}
