Working with Datasets

It is very common to deal with datasets in scripting, as datasets power many of the interesting features in Ignition, like charts and tables. The system.dataset library provides various functions for manipulating and creating datasets.

The main confusion when dealing with datasets is the difference between the DataSet object and the PyDataSet object. DataSet is the kind of object that Ignition uses internally to represents datasets. When you get the data property out of a Table, for example, you'll get a DataSet. The PyDataSet is a wrapper type that you can use to make DataSets more accessible in Python. You can convert between the two with system.dataset.toPyDataSet and system.dataset.toDataSet.

Accessing data in a DataSet

DataSets have various properties and functions that you can access through Python.

rowCount
Returns the number of rows in the dataset.

columnCount
Returns the number of columns in the dataset.

getColumnName(index)
Returns the name of the column at the given index.

getValueAt(row, column)
Returns the value from the dataset at the given location. column can be either an integer or a column name, which is treated case-insensitive.

For example, you could iterate through every item in a DataSet in scripting like this:

# Pull the dataset property off a Table component
data = event.source.getComponent("Table").data
 
for row in range(data.rowCount):
for col in range(data.columnCount):
print data.getValueAt(row, col)

or you could find specific values from each row in a DataSet like this:

# Pull the dataset property off a Table component
data = event.source.getComponent("Table").data
 
for row in range(data.rowCount):
temp = data.getValueAt(row, "Temperature")
speed = data.getValueAt(row, "Speed")
print temp, speed

Accessing data in a PyDataSet

You can convert a dataset to a PyDataSet, which lets you use it more like a Python sequence. You don't have to do this, its purely a convenience. A PyDataSet is like a list of dictionaries, and so it can use the normal for loop syntax. These examples are equivalent to the examples above.

Iterating through a PyDataSet

# Pull the dataset property off a Table component
data = event.source.getComponent("Table").data
 
# Convert to a PyDataSet
pds = system.dataset.toPyDataSet(data)
 
for row in pds:
for value in row:
print value

Finding specific values in a PyDataSet

# Pull the dataset property off a Table component
data = event.source.getComponent("Table").data
 
# Convert to a PyDataSet
pds = system.dataset.toPyDataSet(data)
 
for row in pds:
temp = row["Temperature"]
speed = row["Speed"]
print temp, speed

Accessing specific elements in a PyDataSet

# Pull the dataset property off a Table component
data = event.source.getComponent("Table").data
 
# Convert to PyDataSet
pds = system.dataset.toPyDataSet(data)
 
# Grab the first item of the first row
value = pds[0][0]
print value

Altering Datasets

Technically, you cannot alter a dataset. Datasets are immutable, meaning they cannot change. You can, however, create new datasets. So to change a dataset, you really create a new one and then replace the old one with the new one. Because this is so common, there are special functions under system.dataset that are designed for this.

You can use the following functions to create datasets that are altered version of existing datasets:

  • system.dataset.addRow

  • system.dataset.deleteRow

  • system.dataset.setValue

  • system.dataset.updateRow

The important thing to realize about all of these datasets is that, again, they do not actually alter the input dataset. They return a new dataset. You need to actually use that returned dataset to do anything useful.

For example, the following code would set the Quantity column in the selected row of a table to 15.8:

table = event.source.parent.getComponent("Table")
selRow = table.selectedRow
if selRow != -1:
# Create a new dataset
newData = system.dataset.setValue(table.data, selRow, "Quantity", 15.8)
 
# Replace the Table's data property with the new dataset
table.data = newData

Creating Datasets

Sometimes you'll want to create a new dataset from scratch. This can be easily done with the system.dataset.toDataSet function. All it needs are the column headers and a list of the rows in the dataset. Each row must have the same number of elements as the header list.

For example, the following code would create a dataset that contained some information about US cities:

headers = ["City", "Population", "Timezone", "GMTOffset"]
data = []
 
data.append(["New York", 8363710, "EST", -5])
data.append(["Los Angeles", 3833995, "PST", -8])
data.append(["Chicago", 2853114, "CST", -6])
data.append(["Houston", 2242193, "CST", -6])
data.append(["Phoenix", 1567924, "MST", -7])
 
cities = system.dataset.toDataSet(headers, data)