user_experience_tests.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Come back to this cell later."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Reflection in Jupyter Notebooks!\n",
    "\n",
    "## User experience testing for a python library in development for a final year project.\n",
    "\n",
    "### Charles Varley, 2391564v\n",
    "### The python library in this project provides programmers with the capability to perform reflective programming in the Jupyter Notebook context, this is currently a missing feature of the Jupyter Notebook paradigm .\n",
    "### Due to the nature of this library, it is possible that the state of this notebook might be different depending on how previous users might have interacted with it.\n",
    "### Also, because this notebook is hosted on binder, it is possible that another user may be currently going through the notebook and modifying things. If the server tells you that the notebook has been changed then it is recommended to come back in a few minutes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Execute this command if the library isn't installed on hosting service.\n",
    "# If there is output printed at this cell, it has already been installed.\n",
    "!pip install JupyterNotebookReflection"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then import the package and create a notebook object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import JupyterNotebookReflection as jnr\n",
    "\n",
    "# Create a notebook instance that contains the data of the notebook file itself, \n",
    "# enabling reflective programming within the notebook context.\n",
    "\n",
    "# Important: Construction of notebook object must be done in its own cell, \n",
    "# prior to any reflective programming\n",
    "my_nb = jnr.JupyterNotebook() "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. View the state of cells in the notebook\n",
    "### get_cell(i) = get the state of a cell at index i in the notebook.\n",
    "### get_cells([i range]) = get a tuple of cells at indices 'i range' in the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# View a cell in the notebook.\n",
    "print(my_nb.get_cell(0))\n",
    "\n",
    "# Cell attributes:\n",
    "# ctype = type of cell, either markdown or code\n",
    "# content = the content stored in the cell\n",
    "# index = positional index of the cell in the notebook, starts at 0\n",
    "# prompt = execution counter of the cell, if applicable (the number stored in the In[] annotation)\n",
    "# auto = boolean that tells the cell to execute when any change is made to it via my_nb"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Obtain the contents of the cell\n",
    "content = my_nb.get_cell(0).content\n",
    "print(content)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Make a cell in memory\n",
    "### make_cell(type (optional), content (optional)) = make a cell instance of specified type and content.\n",
    "\n",
    "### Note, JupyterNotebookReflection only supports 'code' or 'markdown' cells currently."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make a cell\n",
    "my_cell = my_nb.make_cell('code', 'print(\\'hello world.\\')')\n",
    "print(my_cell)\n",
    "\n",
    "# my_cell doesn't have an index value because it's not currently set in the notebook itself."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Change the cells in the notebook\n",
    "### set_cell(cell, i) = save cell at index i in the notebook.\n",
    "### set_cells([cell list], [i list]) = save a list of cells at corresponding index values in i list. Note, lists must be the same size."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use deepcopy to copy my_cell, otherwise it get mutated during test.\n",
    "from copy import deepcopy\n",
    "\n",
    "# Save our cell at index 0\n",
    "my_nb.set_cell(deepcopy(my_cell), 0)\n",
    "\n",
    "# The first cell of the notebook is changed to the state of my_cell, you can now scroll up to view this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# You can also pass a boolean to set_cell or set_cells to tell the Notebook object \n",
    "# if you want the cell to be automaticall run or not when it is set.\n",
    "my_new_cell = my_nb.make_cell('code', 'print(\\'goodbye world.\\')')\n",
    "my_nb.set_cell(deepcopy(my_new_cell), 0, False)\n",
    "\n",
    "# The cell is changed but it still has the output from the previous state, \n",
    "# and it can be executed when you want it to."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Change cell type or content\n",
    "### set_cell_type(type, i) = set cell at index i to specified supported type.\n",
    "### set_cell_content(content, i) = set cell at index to contain specified text."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Change cell to markdown\n",
    "my_nb.set_cell_type('markdown', 0)\n",
    "# Lets also change its contents\n",
    "my_nb.set_cell_content('It was snowing today when I wrote this.', 0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# You can also pass a boolean to tell it to not run the cell when it makes the changes.\n",
    "my_nb.set_cell_type('code', 0, False)\n",
    "my_nb.set_cell_content('5+5', 0, False)\n",
    "\n",
    "# The cell is changed and can be executed when you want it to."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Insert new cells\n",
    "### insert_cell(cell, i (optional)) = insert a new cell into the notebook at index i.\n",
    "### insert_cells([cell list], i (optional)) = insert a list of cells into the notebook beginning at index i.\n",
    "\n",
    "### If the index is omitted, then cells will be inserted at the end of the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We still have our cell instances from earlier\n",
    "my_nb.insert_cell(my_cell, 0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Again, you can pass a boolean to tell it to not run the inserted cell\n",
    "my_nb.insert_cell(my_cell, 0, False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Append to cell\n",
    "### append_to_cell(content, i) = add specified content to the end of the cell at index i."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_nb.append_to_cell('print(\\'goodbye world.\\')', 0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Delete cells\n",
    "### delete_cell(i) = delete cell from the notebook at index i.\n",
    "### delete_cells([i list]) = delete cells from the notebook at indices in the list.\n",
    "\n",
    "### Note for delete_cells, you don't have to account for the indices of the cells becoming offset as the Notebook object processes the deletion of cells earlier in the index list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Lets clean up the start of this notebook.\n",
    "my_nb.delete_cells([0,1])\n",
    "\n",
    "# Reset the first cell for the next user.\n",
    "my_nb.set_cell_content('# Come back to this cell later.', 0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 8. Notebook data\n",
    "### get_vars() = get a list of user-defined variables in notebook context.\n",
    "### set_var(var, val) = set variable var to value val. (note, variable name needs to be passed as a string)\n",
    "### get_filename() = get notebook filename\n",
    "### get_filepath() = get notebook filepath (might be unusual since notebook is hosted on binder)\n",
    "### cell_count() = current number of cells in the notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Have a look at variables defined during this test.\n",
    "my_nb.get_vars()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Change a variable and use it.\n",
    "my_nb.set_var('content', 'this content got changed!')\n",
    "content"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# can also re-define methods by using a lambda expression or another function definition\n",
    "my_nb.set_var('content', lambda x: x+2)\n",
    "content(5)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# convenience method to obtain filename using code, if filename isn't guaranteed to be known.\n",
    "my_nb.get_filename()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# another convenience method to obtain filepath as well.\n",
    "my_nb.get_filepath()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# another convenience method to show the number of cells\n",
    "my_nb.cell_count()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 9. Source code generation\n",
    "### source_code([i range] (optional)) = print source code of cells with indices in the range specified in 'i range' \n",
    "\n",
    "### Note, for 'i range' you don't need to consider omittion of markdown or unexecuted cells, they don't get read.\n",
    "### Also note, if 'i range' is omitted, my_nb will print the source code of the entire notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Obtain first 20 code executions\n",
    "print(my_nb.source_code(list(range(20))))\n",
    "\n",
    "# Note this only prints source code that is currently in the notebook itself, \n",
    "# it doesn't recover overwritten cell executions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Thank you very much for taking the time to participate in this test!\n",
    "\n",
    "## I would be very interested in hearing your feedback regarding this library.\n",
    "\n",
    "## Please fill out a short Google forms questionaire!\n",
    "\n",
    "https://forms.gle/EDh24P1joBfeZgTGA"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}