Use the scripting environment

Note:

The Insights scripting environment is available in Insights in ArcGIS Enterprise and Insights desktop. The primary connection can be to either Insights in ArcGIS Enterprise or Insights in ArcGIS Online.

Jupyter Kernel Gateway connections can be disabled for an Insights in ArcGIS Enterprise organization during the installation process. Contact your administrator if the Jupyter Kernel Gateway connections are not available. For more information, see Install Insights in ArcGIS Enterprise.

After a connection is made to a Jupyter Kernel Gateway, the scripting environment can be accessed and used to create and run scripts in Python and R. The scripting environment consists of an In[ ] cell, where scripts are loaded or written; an Out[ ] cell, where results are displayed; and a toolbar.

Open the scripting environment

To use the scripting environment, you must first set up a Jupyter Kernel Gateway and create a connection to the gateway. Once the gateway connection is created, complete the following steps to open the scripting environment and start writing scripts:

1. Open a workbook. Add data to your workbook, if necessary.

   Tip:

   You can also load data from within the scripting environment.

2. Click the Scripting button on the workbook toolbar.
3. If a connection wasn't saved in the workbook previously, do one of the following:
   • In Insights desktop, if the New Jupyter Kernel Gateway connection window opens, it means you have not created a connection to the gateway. Enter the URL and web socket address to your gateway to create the connection. See Connect to a kernel gateway for more information.
   • In Insights in ArcGIS Enterprise, if the Kernel Gateway connection window opens, select an existing kernel gateway connection from the Environment name menu. You can also create a new connection on the Add new tab. See Connect to a kernel gateway for more information.

   The scripting environment opens and a Scripts heading is added to the data pane.

4. Use the Select Kernel menu to choose which kernel to use for scripting. Depending on the kernel gateway connection you are using, the options will be Python, R, or both.

   The scripting environment updates to include an In[ ] cell, as well as a toolbar.

The scripting environment is now ready to create, load, and run scripts.

Your script is automatically saved under the Scripts heading in the data pane with the name Insights Script. The script can be renamed using the Rename script button .

The following options are also available for the script using the Dataset options button :

• Open—Load the script into an In[ ] cell.
• Run—Run the script without opening the scripting environment.
• Download—Download the script as a Jupyter Notebook file (.ipynb).
• Publish—Publish the script to create an Insights script item (available in Insights in ArcGIS Enterprise).
• Remove—Remove the script from the data pane.

Edit a script

Scripts can be edited from the In[ ] cells, even after the cell has been executed. To edit a script, click in the cell, make the edits, then run the cell. A new Out[ ] cell is created with the edited results.

Export a script

Scripts that are written in the scripting environment can be exported and saved as a .py script for Python, or a .R script for R. A script can be exported from the scripting environment by selecting one or more cells and clicking the Export button .

The following export options are available when you save a script:

• Download Selected Cell(s)—Saves only the script in the selected In[ ] cells.
• Download History—Saves the script from all In[ ] cells in the scripting environment as a Jupyter Notebook file (.ipynb).

Exported scripts will be saved in the default download folder on your computer.

Load a script

Scripts can be created directly in the scripting environment by typing in the In[ ] cell. Existing scripts can also be loaded into the scripting environment using the following steps:

1. Open the scripting environment, if necessary, and choose the correct kernel for the script you will be running.
2. Click the Import file button on the scripting environment toolbar.
3. Browse to and open the script you want to run.

   The script is opened in the In[ ] cell.

4. Click the Run button on the scripting environment toolbar.

The script runs and the results appear in the Out[ ] cell.

Scripts that are saved in the data pane can also be loaded into the scripting environment. To load a script from the data pane, use the following steps:

1. Expand the Scripts heading in the data pane.
2. Click the Dataset options button for the script you want to load.
3. Click Open.

   The script is opened in the In[ ] cell.

Create an image card

Scripting results, such as charts, can be exported from an Out[ ] cell to create an image card on your Insights page. To export a cell, you must run your script using the Run button , highlight the Out[ ] cell, and then click the Create Card button to move the image from the most recent Out[ ] cell to an image card.

Note:

Image cards created from scripts are static and do not have the same interactive capabilities of map, chart, and table cards created in Insights.

Save your script to a model

The script in your scripting environment can be added to your model as an Insights script using the Add To Model button . The Insights script can be edited from the Analysis view . For more information on updating a model in Insights, see Rerun your analysis.

Clear or close the scripting environment

The script, including all In[ ] and Out[ ] cells, can be cleared using the Restart button . Clearing the scripting environment cannot be undone.

The scripting environment is closed by clicking the close button or browsing to a different page within Insights.

If you need to switch between the Insights page and the scripting environment, it is best practice to minimize the environment using the minimize button rather than closing it, so you will not lose your scripts.