Integrating Python scripts

You can seamlessly integrate Analytics scripting and Python scripting using the ACLScript Python command. The command allows you to move data back and forth between the two environments, which means that a single data analysis workflow in Analytics can use whichever environment is most suited to a particular task.

How it works

The Python command passes an Analytics table to an external Python script as a dataframe, waits while the Python script executes, and then creates a new table in the Analytics project using the returned output from the Python script. You can use the Python command as many times as required in the course of an Analytics script.

Two Python functions are included with the Analytics installation and you use them in the Python script to input and output data:

• Input data acl_py_util.from_an() imports data from Analytics to Python

• Output data acl_py_util.to_an() exports data from Python to Analytics

Using the Python command for different purposes

The ACLScript Python command offers flexibility and can be used for different purposes.

• Round-trip data Import data from Analytics to Python, perform analysis in Python, and export the analysis results back to Analytics

• Send data one way Import data from Analytics to Python, perform analysis or file transformation in Python, and save the results to a destination or file format other than Analytics

• Send data one way Import data from an external source to Python, perform analysis or file preparation in Python, and export the results to Analytics

• Do not transfer data From Analytics, trigger a Python script to perform a task associated with the overall workflow

Aligning the Analytics and Python scripts

The ACLScript Python command, and the two Python functions for inputting and outputting data, are relatively straightforward to use. However, you must ensure that the ACLScript Python command, and the script logic in the corresponding Python script, are aligned. Lack of alignment causes the integration process to fail. The table below provides guidance.

ACLScript Python command	Python script
Exports data	Data input function must be present: acl_py_util.from_an()
Specifies that data is exported with Analytics field names	Any referenced field names must match the Analytics field names
Specifies the Python script to run	A Python script with a matching name and file path location must exist
Specifies that a table is returned to Analytics	Data output function must be present: acl_py_util.to_an()

Troubleshooting using log files

Analytics creates two log files associated with the ACLScript Python command. The logs can assist you with troubleshooting the integration between Analytics and Python, and with debugging errors in the associated Analytics and Python scripts.

The log files are stored in the Analytics project folder:

• aclpython.log – logs Analytics error messages when the ACLScript Python command fails

• acl_py_util.log – logs informational messages output by the Python script

  acl_py_util.log is a configurable log included with the Analytics installation. For information about how to set up and configure the log, see Set up acl_py_util.log.

Run a Python script

Use the ACLScript Python command to run a Python script from Analytics. The only required information in the command is the file path and name of the Python script that you want to run.

The command allows you to export data from Analytics to the Python script, or return data from the Python script to Analytics. However, transferring data is not a requirement.

1. If you want to export data from Analytics to a Python script, open the table containing the data.

2. From the Analytics main menu, select Analyze > Python.

3. In the Python field, specify the file path and name of the Python script that you want to run.

   For example: C:\Python_data_analysis_scripts\testInOutput.py

   You can click Browse and navigate to the Python script on your computer.

   You can specify a relative path to the Python script, or just the script file name if the script is in the Analytics project folder.

4. If you are exporting data to Python, do the following:

   1. Click Select Fields and add one or more fields to include in the dataframe that Analytics makes available in the Python script.

      Tip

      You can also include expressions as fields in the dataframe. To create an expression, click Expression and use the functions, fields, and operators available to you in the dialog box. For more information, see Expression Builder overview.

   2. Optional. In the Data Export Options section, define how you want to send the Analytics data to the Python script.

      For more information, see Data Export Options.

   3. Optional. To filter the records that are sent to the Python script, click If and use the Expression Builder dialog box to create a conditional expression to use as the filter.

      For more information about creating expressions using the Expression Builder, see Creating expressions using the Expression Builder.

5. If you are returning data from Python, do the following:

   1. In the To text box, specify a name for the table to contain the returned data.

      You can click To and use the file explorer to navigate to the folder you want to use to store the source data file.

      Note

      Analytics table names are limited to 64 alphanumeric characters, not including the .FIL extension. The name can include the underscore character ( _ ), but no other special characters, or any spaces. The name cannot start with a number.

   2. Select Use Output Table if you want the table to open automatically upon completion of the operation.

6. Optional. On the More tab of the dialog box, specify any scope options that you want to use.

   For more information, see More tab.

7. Click OK to run the command.

   If you get an error message and the Python command, or the Python script, fails to run, verify that the Python Path value in the Options dialog box is correctly specified. For more information, see Add the virtual environment path to the Analytics Options.

PYCOMMAND dialog box options

Data Export Options

Option	Description
Export with field names	Use the field names of the source Analytics table as column names for the Python dataframe. This option sets the KEEPTITLE option on the command and is required if you want to retrieve data using column names in the Python script.
Column Separator	The character to use as the separator between fields when sending data to Python.
Text Qualifier	The character to use as the text qualifier to identify field values when sending data to Python.

More tab

Option	Description
All	Processes all records in the view (default selection).
First	Processes from the first record in the table and includes only the specified number of records.
Next	Processes from the currently selected record in the table and includes only the specified number of records. Note The number of records specified in the First or Next options references either the physical or the indexed order of records in a table, and disregards any filtering or quick sorting applied to the view. However, results of analytical operations respect any filtering. If a view is quick sorted, Next behaves like First.
While	Uses a WHILE statement to limit the processing of records in the primary table based on criteria. Records in the view are processed only while the specified condition evaluates to true. As soon as the condition evaluates to false, the processing terminates, and no further records are considered. For more information, see Creating expressions using the Expression Builder.