Package: openad
OpenAD BetaOpen Accelerated Discovery ClientDocumentationOpenAD is an open-source framework developed by IBM Research, aggregating a number of molecular science toolkits into a single API that can be accessed by command line, a Jupyter Notebook and (soon) an API.The goal of openAD is to provide a common language for scientists to interact with a multitude of of molecular tools to simplify the triage process and drastically accelerate your development timelines.Pre-install Note:For updating to 0.2.0 first remove toolkitsremove toolkit DS4SDandremove toolkit RXNprior to updatingWhats New ?Increased number of Molecules Functions for retrieving from pubchem molecules or creating your own in a working set, including visualisation, tracking of source info3D displaying of molecules in your working set or direct from pubchemAttaching Analysis to target Molecules with theenrichcommandEnhanced Help and Tell Me commandLinking to source documents in DeepSearchmerging molecules and molsets togethereasy access to dataframes and results sets with the newresultcommandsmaller install packageintroductory molecule viewerNote: uninstall all toolkits before installing the new versionQuick InstallNote:This will install OpenAD in your global space. If you wish to use a virtual environment, please see moredetailed instructionsbelow.pip install openad
openadGet started with Jupyter:init_magic
init_examples
jupyter lab ~/openad_notebooks/Table_of_Contents.ipynbBefore You StartOpenAD is available for Linux and MacOSWe support Windows 11 via WSL 2 (ubuntu 22.04) - seeInstalling on WindowsWhen not installing into a virtual environment on MacOS, you may need to usepython3andpip3instead ofpythonandpiprespectivelyTable of ContentsOpenAD BetaInstallationGetting Started - CLIGetting Started - JupyterSetting up JupyterLaunching OpenAD in JupyterInteracting with the ToolkitsRegistrationAdding a ToolkitSample CommandsRunning Bash Commands (CLI)AI AssistantFor DevelopersInstallation for DevelopmentTesting a branchInstalling on WindowsBefore you startInstalling WSLLinux NotesInstallationNote:Contributors should skip toInstallation for DevelopmentNote:Linux users may want to check theLinux NotesNote:If you prefer using poetry and you know what you're doing, you can skip the instructions below and runpoetry add openadinstead.Step 0: Before you startEnsure you're running Python 3.10 or 3.11. There's multiple ways of updating Python, we'll use pyenv.Note:Due to an issue with one of our dependencies, Python 3.12 is not yet supported.git clone https://github.com/pyenv/pyenv.git ~/.pyenv
pyenv install 3.10Step 1: Set up your virtual environment(optional)python -m venv ~/ad-venv
source ~/ad-venv/bin/activateNote:To exit the virtual environment, you can rundeactivateStep 2: Installationpip install openadGetting Started - CLIEnter the virtual environmentNote:If you just installed OpenAD, you probably already activated the virtual environment.source ~/ad-venv/bin/activateEnter the command shellopenadExit the command shellHitctrl+cor run:exitRun a single command from outside the command shellopenad <command>Exit the virtual environmentdeactivateGetting Started - JupyterSetting up JupyterThe following commands only need to be run once after installation:Activate your virtual environmentNote:If you just installed OpenAD, you probably already activated the virtual environment.source ~/ad-venv/bin/activateCreate an iPython kernelThis ports your virtual environment to Jupyter.python -m ipykernel install --user --name=ad-venvNote:To list your installed iPython kernels, you can runjupyter kernelspec list, and to remove the kernel you can runjupyter kernelspec uninstall ad-venvInstall the magic commandsThis enables OpenAD commands to be run within a Jupyter Notebook.init_magicAlternative:Manually add magic commandsIf you don't want to activate magic commands in all Notebooks, you can instead activate them for individual Notebooks.Runinit_examplesCopy the file~/openad_notebooks/openad.ipynbto the same directory as the Notebook you wish to activate.In your Notebook, run this inside a code cell:!run openad.ipynbInstall example NotebooksThis installs our example Notebooks at~/openad_notebooks.init_examplesLaunching OpenAD in JupyterOpen any NotebookThe following command will open up the example Notebook:jupyter lab ~/openad_notebooks/Table_of_Contents.ipynbSelect the kernelMake sure to select the "ad-venv" iPython kernel. You can do this underKernel > Change Kernel, or in the latest versions of Jupyter by clicking the kernel name in the top right hand corner. If you don't see your iPython kernel, make sure you followed the Jupyter Setup instructions listed above.Jupyter NotebookJupyter LabMagic CommandsMagic commands let you run terminal commands from within Jupyter. They are invoked by the%openadprefix. All OpenAD CLI commands can be accessed like this. For example:%openad list filesInteracting with the ToolkitsOpenAD integrates withDS4SD,RXN, and has placeholder support forGT4SDandST4SD.⚠ Reminder:when running commands from Jupyter, prepend them with%openadRegistrationBefore you can interact with the toolkits, you'll need to register with each individual toolkit.Register with DS4SD (Deep Search)First, you'll need to generate an API key on the Deep Search website.Visit the Deep Search website and create an account:deepsearch-experience.res.ibm.comOnce logged in, click the Toolkit/API icon in the top right hand corner, then open the HTTP sectionClick the "Generate new API key" buttonOnce inside the OpenAD client, you'll be prompted to authenticate when activating the Deep Search (DS4SD) toolkit. When runningset context ds4sd:Hostname:https://sds.app.accelerate.scienceEmail:Your emailAPI_key:The DS4SD API key you obtained following the instructions above.You should get a message saying you successfully logged in.Note:Your DS4SD auth config file is saved as~/.openad/deepsearch_api.cred. If you ever want to reset your DS4SD login information you can runset context ds4sd reset, or you can delete this file.Register with RXNFirst, you'll need to generate an API key on the RXN website.Sign up for an RXN account atrxn.app.accelerate.scienceObtain your API key by clicking the user profile icon in the top right hand corner and select "My profile".When setting the context to RXN usingset context rxnyou'll be prompted to create a new auth configuration file:Hostname:https://rxn.app.accelerate.scienceAPI_key:The RXN API key you obtained following the instructions above.You should get a message saying you successfully logged in.Note:Your RXN auth config file is saved as~/.openad/rxn_api.cred. If you ever want to reset your RXN login information you can runset context rxn reset, or you can delete this file.Adding a ToolkitFirst install the toolkit, then set the context to this toolkit.add toolkit ds4sd
set context ds4sdSample Commands# DS4SD
display all collections

# RXN
list rxn modelsRunning Bash Commands (CLI)To run a command in bash mode, prepend it withopenadand make sure to escape quotes.openad show molecules using file \'base_molecules.sdf\'AI AssistantTo enable our AI assistant, you'll need an account with OpenAI. There is a one month free trial.Note:watsonx coming soonGo toplatform.openai.comand create an accountClick on the profile icon in the top right and choose "View API keys"Create a new keyRuntell meto be prompted for your OpenAI API credentialsFor DevelopersOpenAD is fully open source and we encourage contributions. We plan to provide documentation on how to integrate your own toolkits in the future.If you have any questions in the meantime, please [reach out]({% link about.md %}).Installation for DevelopmentInstall using the setup wizard (uses poetry)Step 1: Download the repogit clone https://github.com/acceleratedscience/open-ad-toolkit.gitNote:To download a specific branch, you can run instead:git clone -b <branch_name> https://github.com/acceleratedscience/open-ad-toolkit.gitStep 2: Launch the setup wizardcd open-ad-toolkit
./setup.shInstall using pipStep 0: Before you startEnsure you're running Python 3.10.10 or above. There's multiple ways of doing this, we'll use pyenv.git clone https://github.com/pyenv/pyenv.git ~/.pyenv
pyenv install 3.10Step 1: Set up your virtual environment(optional)python -m venv ~/ad-venv
source ~/ad-venv/bin/activateNote:To exit the virtual environment, you can rundeactivateStep 2: Download the repogit clone https://github.com/acceleratedscience/open-ad-toolkit.gitNote:To download a specific branch, you can run instead:git clone -b <branch_name> https://github.com/acceleratedscience/open-ad-toolkit.gitStep 2: Install the requirementscd open-ad-toolkit
pip install -e .Note:The -e flag stands for "editable". This means that instead of copying the package's files to the Python site-packages directory as in a regular installation, pip creates a symbolic link (symlink) from your package's source code directory into your Python environment.This way you can make changes to the source code of the package, and those changes are immediately reflected in your Python environment. You don't need to reinstall the package every time you make a change.Testing a branchTo do a regular install from a particular branch, you can run:pip install git+https://github.com/acceleratedscience/open-ad-toolkit.git@<branch_name>Installing on WindowsIn order to run OpenAD on Windows 11, you will need to install the Ubuntu WSL package ("Windows Subsystem for Linux").Before you startVerify Windows versionTo check if you are running Windows 11 or later, pressWin+R, type "winver", and pressEnter. A window will open showing your Windows version.Verify WSLTo check if you already have WSL installed, runwsl -l -vinto the terminal. To see more information about your current version of Ubuntu, runlsb_release -aInstalling WSLInstall WSL and create a user called 'openad' or one of your choosing.wsl --install Ubuntu-22.04Optional:To setup an Ubuntu Python environment from scratch, continue toLinux NotesLinux NotesIf you wish to setup an Ubuntu Python environment from scratch, run:sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11-full
sudo apt install python3-pip
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 100
sudo pip install pip --upgradeIf you get an error when runninginit_magic, you may first need to setup the default iPython profile for magic commands.ipython profile create