Skip to main content

TableToNumPyArray

Summary

The TableToNumPyArray function converts a table to a NumPy structured array.

Discussion

NumPy is a fundamental package for scientific computing in Python, including support for a powerful N-dimensional array object. For more information, see NumPy in ArcGIS.

To convert feature classes to a NumPy array, use the FeatureClassToNumPyArray function instead.

Syntax

TableToNumPyArray(in_table, field_names, {where_clause}, {skip_nulls}, {null_value})

Parameter Explanation Data Type

in_table

The feature class, layer, table, or table view.

String

field_names

A list (or tuple) of field names. For a single field, you can use a string instead of a list of strings.

Use an asterisk (*) instead of a list of fields to access all fields from the input table (BLOB fields are excluded). However, for faster performance and reliable field order, it is recommended that the list of fields be narrowed to only those that are actually needed.

Raster and BLOB fields are not supported. Geometry objects are not supported using the SHAPE@ token, but geometry information can be included using other tokens such as SHAPE@XY (a tuple of the feature's centroid coordinates), SHAPE@AREA, and SHAPE@LENGTH.

Additional information can be accessed using tokens (such as OID@) in place of field names:

  • OID@—Returns the value of the ObjectID field.

The default value is *.

String

where_clause

An optional expression that limits the records returned. For more information on WHERE clauses and SQL statements, see SQL reference for query expressions used in ArcGIS.

The default value is "".

String

skip_nulls

Control whether records using nulls are skipped. It can be either a Boolean True or False, or a Python function or lambda expression.

When set to True, if any of the record's attributes is null (including geometry), the record is skipped. With a False setting, skip_nulls attempts to use all records regardless of nulls. In a NumPy array, a null is represented as a nan (not a number) for floating-point numeric values but not for integers.

The following is an example of skipping all records that include a null.

import arcpy
array = arcpy.da.TableToNumPyArray(table, fields, skip_nulls=True)

A Python function or lambda expression can be used to allow finer control, including logging the OID values of all records that include a null value. In both examples below, the lambda expression or function is used to identify OIDs that include null records.

Use a function to capture all records that are skipped because of nulls.

import arcpy

def getnull(oid):
    nullRows.append(oid)
    return True

nullRows = list()
array = arcpy.da.TableToNumPyArray(table, fields, skip_nulls=getnull)
print(nullRows)

Use a lambda expression to capture all records that are skipped because of nulls.

import arcpy
nullRows = list()
array = arcpy.da.TableToNumPyArray(
    table, fields, skip_nulls=lambda oid: nullRows.append(oid))
print(nullRows)
Note:

In NumPy arrays, nulls are represented in float types such as nan and in text types such as None. Integer types do not support the concept of null values.

The default value is False.

Variant

null_value

Replaces null values from the input with a new value.

null_value is replaced before skip_nulls is evaluated.

Mask None values in integer fields with a -9999.

import arcpy
fields = ['field1', 'field2']
arcpy.da.TableToNumPyArray(table, fields, null_value=-9999)

Mask None values in integer fields with different values using a dictionary.

import arcpy
fields = ['field1', 'field2']
nullDict = {'field1':-999999, 'field2':-9999}
arcpy.da.TableToNumPyArray(table, fields, null_value=nullDict)
Caution:

Providing a mask such as -9999 allows integer fields containing nulls to be exported to a NumPy array, but be cautious when using these values in any analysis. The results may be inadvertently skewed by the introduced value.

The default value is None.

Integer

Return value

Data Type Explanation

NumPyArray

A NumPy structured array.

Code sample

TableToNumPyArray example 1

Convert a table to a NumPy array and perform basic statistics with NumPy.

import arcpy
import numpy

input = "c:/data/usa.gdb/USA/counties"
arr = arcpy.da.TableToNumPyArray(input, ("STATE_NAME", "POP1990", "POP2000"))

# Sum the total population for 1990 and 2000
print(arr["POP1990"].sum())
print(arr["POP2000"].sum())

# Sum the population for the state of Minnesota
print(arr[arr["STATE_NAME"] == "Minnesota"]["POP2000"].sum())
TableToNumPyArray example 2

Use the TableToNumPyArray function to determine correlation coefficients for two fields.

import arcpy
import numpy

input = arcpy.GetParameterAsText(0)
field1 = arcpy.GetParameterAsText(1)
field2 = arcpy.GetParameterAsText(2)

arr = arcpy.da.TableToNumPyArray(input, (field1, field2))

# Print correlation coefficients for comparison of 2 field values
print(numpy.corrcoef((arr[field1], arr[field2])))