{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "a52ed53a",
   "metadata": {},
   "source": [
    "# Getting Documentation via Help()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6aa359b4",
   "metadata": {},
   "source": [
    "## Load AUViewer API & Print Help for API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "fa97563e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Import the AUViewer API and set the data path\n",
    "import auviewer.api as api\n",
    "api.setDataPath('~/myproject')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "bc7c36c4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on module auviewer.api in auviewer:\n",
      "\n",
      "NAME\n",
      "    auviewer.api - Python API for working with AUViewer.\n",
      "\n",
      "FUNCTIONS\n",
      "    downsampleFile(filepath: str, destinationpath: str) -> bool\n",
      "        Downsamples an original file, placing the processed file in the destination folder.\n",
      "        Raises an exception in case of error.\n",
      "        :param filepath: path to the original file\n",
      "        :param destinationpath: path to the destination folder\n",
      "        :return: None\n",
      "    \n",
      "    getProject(id) -> Union[auviewer.project.Project, NoneType]\n",
      "        Returns the project with matching ID.\n",
      "        :return: the project instance belonging to the id, or None if not found\n",
      "    \n",
      "    getProjects() -> Dict[int, auviewer.project.Project]\n",
      "        Returns loaded projects as a dict.\n",
      "        :return: dict mapped from project ID to project instance of all loaded projects\n",
      "    \n",
      "    getProjectsPayload(user_id) -> List[Dict]\n",
      "        Returns a list of project information accessible to a given user.\n",
      "        :return: list of objects containing project information\n",
      "    \n",
      "    listAvailableProjects() -> List[List[str]]\n",
      "        Returns list of available projects (ID, name, path) from the database.\n",
      "        These projects are not necessarily loaded in memory (that is done using\n",
      "        loadProjects() or loadProject().\n",
      "        :return:\n",
      "    \n",
      "    listLoadedProjects() -> List[List[str]]\n",
      "        Returns list of projects loaded in memory (ID, name, path).\n",
      "        :return: list of lists\n",
      "    \n",
      "    listUsers() -> List[List[str]]\n",
      "        Returns list of users (ID, email, first name, last name)\n",
      "        :return: list of lists\n",
      "    \n",
      "    loadProject(id) -> Union[auviewer.project.Project, NoneType]\n",
      "        Load a project into memory. Returns the project instance if successful.\n",
      "        :return: the project instance, or None\n",
      "    \n",
      "    loadProjects() -> Dict[int, auviewer.project.Project]\n",
      "        Load or reload projects into memory. If new projects are found on disk, they\n",
      "        will be added to the database & loaded as well. Returns the same output as\n",
      "        getProjects().\n",
      "        :return: dict mapped from project ID to project of all loaded projects\n",
      "    \n",
      "    scaffoldProjectFolder(projDirPathObj)\n",
      "        Generate the baseline project folder contents as needed\n",
      "    \n",
      "    setDataPath(path, load_projects=False) -> None\n",
      "        Loads a data path for use via Python (instead of as a web server). If the\n",
      "        optional load_projects parameter is False, then projects must be loaded\n",
      "        manually using loadProject() or loadProjects().\n",
      "    \n",
      "    validateProjectFolder(projDirPathObj)\n",
      "        Raises an exception if the project folder is invalid\n",
      "\n",
      "DATA\n",
      "    Dict = typing.Dict\n",
      "    List = typing.List\n",
      "    Optional = typing.Optional\n",
      "    config = {'M': 3000, 'builtinDefaultInterfaceTemplates': '{\\n\\t\"realti...\n",
      "    loadedProjects = []\n",
      "\n",
      "FILE\n",
      "    /Users/guswelter/miniconda3/envs/auv/lib/python3.8/site-packages/auviewer/api.py\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Print help documentation for api (these will be the top-level methods available)\n",
    "help(api)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0addd58e",
   "metadata": {},
   "source": [
    "## Load Project & Print Help for Project"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e4314e7f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[1, 'my_new_project', '/Users/guswelter/myproject/projects/my_new_project']]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# List available projects\n",
    "api.listAvailableProjects()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "6cf2f662",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Load project\n",
    "p = api.loadProject(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "c5628a90",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on Project in module auviewer.project object:\n",
      "\n",
      "class Project(builtins.object)\n",
      " |  Project(projectModel, processNewFiles=True)\n",
      " |  \n",
      " |  Represents an auviewer project.\n",
      " |  \n",
      " |  Methods defined here:\n",
      " |  \n",
      " |  __del__(self)\n",
      " |      Cleanup\n",
      " |  \n",
      " |  __init__(self, projectModel, processNewFiles=True)\n",
      " |      The project name should also be the directory name in the projects directory.\n",
      " |  \n",
      " |  createPatternSet(self, name: str, description=None, showByDefault: bool = True) -> auviewer.patternset.PatternSet\n",
      " |      Create and return a new pattern set.\n",
      " |      :return: a new PatternSet instance\n",
      " |  \n",
      " |  detectPatterns(self, type, series, thresholdlow, thresholdhigh, duration, persistence, maxgap, expected_frequency=0, min_density=0)\n",
      " |      Run pattern detection on all files, and return a DataFrame of results.\n",
      " |      This DataFrame, or a subset thereof, can be passed into PatternSet.addPatterns() if desired.\n",
      " |  \n",
      " |  getAnnotations(self, annotation_id: Union[int, List[int], NoneType] = None, file_id: Union[int, List[int], NoneType] = None, pattern_id: Union[int, List[int], NoneType] = None, pattern_set_id: Union[int, List[int], NoneType] = None, series: Union[~AnyStr, List[~AnyStr], NoneType] = None, user_id: Union[int, List[int], NoneType] = None) -> pandas.core.frame.DataFrame\n",
      " |      Returns a dataframe of annotations for this project, optionally filtered.\n",
      " |  \n",
      " |  getAnnotationsOutput(self, user_id: int)\n",
      " |      Returns a list of user's annotations for all files in the project\n",
      " |  \n",
      " |  getFile(self, id)\n",
      " |      Returns the file with matching ID or None.\n",
      " |  \n",
      " |  getFileByFilename(self, filename)\n",
      " |      Returns the file with matching filename or None.\n",
      " |  \n",
      " |  getInitialPayload(self, user_id)\n",
      " |      Returns initial project payload data\n",
      " |  \n",
      " |  getPatternSet(self, id) -> Union[auviewer.patternset.PatternSet, NoneType]\n",
      " |      Get project's pattern set by ID.\n",
      " |      :return: the PatternSet instance belonging to the id, or None if not found\n",
      " |  \n",
      " |  getPatternSets(self) -> Dict[int, auviewer.patternset.PatternSet]\n",
      " |      Get project's pattern sets.\n",
      " |      :return: a dict of the project's PatternSet instances, indexed by id\n",
      " |  \n",
      " |  getPatterns(self, file_id: Union[int, List[int], NoneType] = None, pattern_id: Union[int, List[int], NoneType] = None, pattern_set_id: Union[int, List[int], NoneType] = None, series: Union[~AnyStr, List[~AnyStr], NoneType] = None, user_id: Union[int, List[int], NoneType] = None) -> pandas.core.frame.DataFrame\n",
      " |      Returns a dataframe of patterns for this project, optionally filtered.\n",
      " |  \n",
      " |  getTotalPatternCount(self) -> int\n",
      " |      Get total count of patterns in all the project's pattern sets\n",
      " |      :return: number of patterns\n",
      " |  \n",
      " |  listFiles(self) -> List[List[str]]\n",
      " |      Returns list of files for the project (ID, filename, file path, downsample path).\n",
      " |      :return: list of lists\n",
      " |  \n",
      " |  listPatternSets(self) -> List[List[str]]\n",
      " |      Returns list of pattern sets (ID, names).\n",
      " |      :return: list of l:return:\n",
      " |  \n",
      " |  loadPatternSets(self) -> None\n",
      " |      Load or reload the project's pattern sets.\n",
      " |  \n",
      " |  loadProjectFiles(self, processNewFiles=True)\n",
      " |      Load or reload files belonging to the project, and process new files if desired.\n",
      " |  \n",
      " |  setName(self, name)\n",
      " |      Rename the project.\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Data descriptors defined here:\n",
      " |  \n",
      " |  __dict__\n",
      " |      dictionary for instance variables (if defined)\n",
      " |  \n",
      " |  __weakref__\n",
      " |      list of weak references to the object (if defined)\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Print help documentation for project\n",
    "help(p)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "518b7616",
   "metadata": {},
   "source": [
    "## Load File & Print Help for File"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "491ed9c1",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[1,\n",
       "  'sample_patient.h5',\n",
       "  '/Users/guswelter/myproject/projects/my_new_project/originals/sample_patient.h5',\n",
       "  '/Users/guswelter/myproject/projects/my_new_project/processed/sample_patient_processed.h5']]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# List project files\n",
    "p.listFiles()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "b2c94305",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a project file\n",
    "f = p.getFile(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "345ac2a6",
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on File in module auviewer.file object:\n",
      "\n",
      "class File(builtins.object)\n",
      " |  File(projparent, id, origFilePathObj, procFilePathObj, processNewFiles=True, processOnly=False)\n",
      " |  \n",
      " |  Represents a project file. File may operate in file- or realtime-mode. In file-mode, all data is written to & read\n",
      " |  from a file. In realtime-mode, no file is dealt with and instead everything is kept in memory. If no filename\n",
      " |  parameter is passed to the constructor, File will operate in realtime-mode.\n",
      " |  \n",
      " |  Methods defined here:\n",
      " |  \n",
      " |  __del__(self)\n",
      " |  \n",
      " |  __init__(self, projparent, id, origFilePathObj, procFilePathObj, processNewFiles=True, processOnly=False)\n",
      " |      Initialize self.  See help(type(self)) for accurate signature.\n",
      " |  \n",
      " |  addSeriesData(self, seriesData)\n",
      " |      Takes new data to add to one or more data series for the file (currently\n",
      " |      works only in realtime-mode). The new data is assumed to occur after any\n",
      " |      existing data. The parameter, seriesData, should be a dict of dicts of\n",
      " |      lists as follows:\n",
      " |      \n",
      " |        {\n",
      " |          'seriesName': {\n",
      " |            'times': [ t1, t2, ... , tn ],\n",
      " |            'values': [ v1, v2, ... , vn ]\n",
      " |          }, ...\n",
      " |        }\n",
      " |      :param seriesData: dict of dicts\n",
      " |      :return: updated file data for transmission to realtime subscribers\n",
      " |  \n",
      " |  createAnnotation(self, user_id, left=None, right=None, top=None, bottom=None, seriesID='', label='', pattern_id=None)\n",
      " |      Create an annotation for the file\n",
      " |  \n",
      " |  deleteAnnotation(self, user_id, id)\n",
      " |      Deletes the annotation with the given ID, after some checks. Returns true or false to indicate success.\n",
      " |  \n",
      " |  detectPatterns(self, type, series, thresholdlow=None, thresholdhigh=None, duration=300, persistence=0.7, maxgap=300, series2=None, expected_frequency=0, min_density=0)\n",
      " |      # TODO(gus): Turn this into DataFrame output in line with Project.detectPatterns.\n",
      " |  \n",
      " |  getEvents(self)\n",
      " |      Returns all event series\n",
      " |  \n",
      " |  getInitialPayload(self, user_id)\n",
      " |      Produces JSON output for all series in the file at the maximum time range.\n",
      " |  \n",
      " |  getMetadata(self)\n",
      " |      Returns a dict of file metadata.\n",
      " |  \n",
      " |  getSeries(self, seriesid)\n",
      " |      Returns the series instance corresponding to the provided series ID, or None if the series cannot be found.\n",
      " |      The seriesid format is [full_series_path]:[value_column], e.g. /data/numerics/HR:value.\n",
      " |  \n",
      " |  getSeriesNames(self)\n",
      " |      Returns a list of series names available in the file.\n",
      " |  \n",
      " |  getSeriesOrCreate(self, seriesid)\n",
      " |      Retreves or creates & returns the series corresponding to the provided series ID.\n",
      " |  \n",
      " |  getSeriesRangedOutput(self, seriesids, start, stop)\n",
      " |      Produces JSON output for a given list of series in the file at a specified time range.\n",
      " |  \n",
      " |  load(self)\n",
      " |      Loads the necessary data into memory for an already-processed data file\n",
      " |      (does not load data though). Sets up classes for all series from file but\n",
      " |      does not load series data into memory).\n",
      " |  \n",
      " |  loadSeriesFromDataset(self, ds)\n",
      " |      Load all available series from a dataset\n",
      " |  \n",
      " |  mode(self)\n",
      " |      Returns the mode in which File is operating, either \"file\" or \"realtime\".\n",
      " |  \n",
      " |  process(self)\n",
      " |      Process and store all downsamples for all series for the file.\n",
      " |  \n",
      " |  updateAnnotation(self, user_id, id, left=None, right=None, top=None, bottom=None, seriesID='', label='')\n",
      " |      Update an annotation with new values\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Readonly properties defined here:\n",
      " |  \n",
      " |  f\n",
      " |  \n",
      " |  pf\n",
      " |  \n",
      " |  ----------------------------------------------------------------------\n",
      " |  Data descriptors defined here:\n",
      " |  \n",
      " |  __dict__\n",
      " |      dictionary for instance variables (if defined)\n",
      " |  \n",
      " |  __weakref__\n",
      " |      list of weak references to the object (if defined)\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# Print help documentation for file\n",
    "help(f)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e16b5924",
   "metadata": {},
   "source": [
    "## And so forth..."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ecf9d92",
   "metadata": {},
   "source": [
    "The same type of help() documentation is available for any object you load, such as pattern sets, patterns, annotation sets, and annotations."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.11"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}