Using JupyterLab¶
JupyterLab is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations, and explanatory text. You can utilize Jupyter to access functions not available in the ContraxSuite UI, to either pull data from ContraxSuite or modify existing code.
This guide is intended to help Technical Admins use JupyterLab within ContraxSuite. This is a supplement to help work with an existing notebook - this is not a guide on how to write notebooks from scratch, nor is it a tutorial on Python.
WARNING: Jupyter-based code can significantly alter data and system configuration. Jupyter can be a very formidable tool, but also has the potential to create unintended consequences. Access to JupyterLab within ContraxSuite should be limited to very specific users, and caution should always be taken when utilizing ancillary code.
How to Deploy Jupyter Code in ContraxSuite¶
1. Access Jupyter for ContraxSuite at [YOURCONTRAXSUITEURL].contraxsuite.com/jupyter/lab
2. You will be prompted for a username and password. Log in using your Administrator credentials.
3. You will then be prompted to put in just a password on the Jupyter page. This login may or may not be the same Administrator password used in the previous prompt.
4. ContraxSuite packages and deploys a set of out-of-the-box Jupyter notebooks accessible from Jupyter. Do not put any new files in the root location or the demo location.
WARNING: All files you want to add must go in the
persistent_volumedirectory.
Uploading Python Code Using JupyterLab¶
An administrator in ContraxSuite may share Jupyter python code between their team, their data scientists, and a LexPredict support team. In order to use JupyterLab to deploy code, you will need to upload the code onto your instance of ContraxSuite. Transfer the code files onto the ContraxSuite instance where you’ll be running the code, and then follow these steps:
1. Click the “Upload” button in the upper right corner, then navigate and choose the file you wish to upload.
2. You will then see the file name listed with a new blue “Upload” button to the right. Click the “Upload” button.
3. Once the code files are uploaded you will be able to find them in the persistent_volume folder. Double-click on persistent_volume, then find the code files you’re looking for in the list, and double-click on them.
4. The Jupyter code will open in the interface. The example below uses Django objects (ContraxSuite uses a DjangoJS backend). The code in the red box contains basic information about these Django objects.
This is the first “cell” in the notebook. There are multiple subsequent cells following the first. You will need to update the sys.path.append('../../') line of this cell to reflect the folder you put the file in. If you are in a sub-folder of the Jupyter Notebook, then the above path would be correct. If you are 2 sub-folders deep, then you would need to change the line to ('../../../'). If you put your file into the root Jupyter folder, then you will only need ('../').
5. To run or apply this code in ContraxSuite, first make sure the correct cell is highlighted. (In the image above you can see the referenced cell is highlighted by a thick blue line and surrounding grey outline.) Hit the “Run” button in the top menu bar. You will initially see a * in the brackets to the left of the cell (In[*]). When the cell is finished running, this * will be replaced by a number. In this case, you will now see a 1 in the brackets after hitting “Run”, and will also see some new text has been generated to provide context, as well as any warnings that occurred.
6. After the first cell runs, the next cell in the sequence will be highlighted.
7. As you continue to run each subsequent cell, the [] will populate with a number, and the next cell will then be highlighted. You will need to hit “Run” on every cell manually, but before you run each cell, you should review output to determine if anything needs to be modified. In the example below, Cell 3 will create an output named DocumentFields.csv. You can change the name in the cell if you wish. More importantly, in the next cell there is a list of Fields that will appear as columns in DocumentFields.csv. If you want your output to pull values from Fields other than those listed in this cell, you can modify that cell before clicking “Run”.
8. In the below example, “exclude_regexps” has been deleted from the list in Cell 4. The subsequent cell, Cell 5, was also run, resulting in a display of the selected outputs from DocumentFields.csv. Note that “exclude_regexps” is not a column header in the .csv file.
9. When you have run all the cells, you will see a blank cell with no content appear as the final cell.
10. Depending on what actions the Jupyter Notebook executed, you can look in the system for any changes that were applied. In our example so far, the Jupyter Notebook was applied to run a report, pull information from the system, and create a .csv file. The line containing the code to_csv or to_excel will contain a file name, in our example, DocumentFields.csv. If there is a path specified, the file will be output to that path. If only a filename is provided, the file will be output to the same folder the code runs from.
In this example, the report ran from the persistent_volume folder, so the output file will also be located in the persistent_volume folder. In addition, the output document, DocumentFields.csv has been created and correctly named, and appears in the list. Note the right hand column says it was last modified only seconds ago.
11. Finally, to open the document, click on the box to the left of the document name and then click “Download” in the top menu.
Tips for Using Jupyter Notebooks¶
Sometimes running the code in a particular cell can result in a timeout if it sits for a long time. If this happens, select Kernel > Restart. This will refresh the connection so the code can run.
To run a notebook, click on the top cell, then click “Run”, then click on the next cell and click “Run”, and so on until there is an error or you get your desired output. Stop if you get errors and don’t know why (other than the timeout error specified above, in which case you can just restart the Kernel).