Complete Numpy API for ONNX

The numpy API is meant to simplofy the creation of ONNX graphs by using functions very similar to what numpy implements. This page only makes a list of the available functions. A tutorial is available at Numpy to ONNX: Create ONNX graphs with an API similar to numpy. This API was first added to mlprodict in version 0.6.

Introduction

Converting custom code into ONNX is not necessarily easy. One big obstacle is ONNX does not represent all numpy functions with a single operator. One possible option is to provide a numpy API to ONNX. That’s the purpose of wrapper onnxnumpy. It takes a function written with functions following the same signature as numpy and provides a way to execute them with an ONNX runtime. In the below example, custom_fct creates an ONNX graph, the wrapper loads it in a runtime and runs it everytime the function is called.

<<<

import numpy
from typing import Any
from mlprodict.npy import onnxnumpy_default, NDArray
import mlprodict.npy.numpy_onnx_impl as nxnp


@onnxnumpy_default
def custom_fct(x: NDArray[Any, numpy.float32],
               ) -> NDArray[Any, numpy.float32]:
    "onnx numpy abs"
    return nxnp.abs(x) + numpy.float32(1)


x = numpy.array([[6.1, -5], [3.5, -7.8]], dtype=numpy.float32)
y = custom_fct(x)
print(y)

>>>

    [[7.1 6. ]
     [4.5 8.8]]

Annotations are mandatory to indicate inputs and outputs type. The decorator returns a function which is strict about types as opposed to numpy. This approach is similar to what tensorflow with autograph.

Signatures

mlprodict.npy.NDArray (self, args, kwargs)

Used to annotation ONNX numpy functions.

ShapeType (params)

Stores shape information.

mlprodict.npy.NDArraySameType (self, dtypes = None)

Shortcut to simplify signature description.

mlprodict.npy.NDArraySameTypeSameShape (self, dtypes = None)

Shortcut to simplify signature description.

mlprodict.npy.onnx_numpy_annotation.NDArrayType (self, dtypes = None, dtypes_out = None, n_optional = None, nvars = False)

Shortcut to simplify signature description.

mlprodict.npy.onnx_numpy_annotation.NDArrayTypeSameShape (self, dtypes = None, dtypes_out = None, n_optional = None, nvars = False)

Shortcut to simplify signature description.

Decorators

mlprodict.npy.onnxnumpy (op_version = None, runtime = None, signature = None)

Decorator to declare a function implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxnumpy_default (fct)

Decorator with options to declare a function implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxnumpy_np (op_version = None, runtime = None, signature = None)

Decorator to declare a function implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_class (method_name, op_version = None, runtime = None, signature = None, method_names = None, overwrite = True)

Decorator to declare a converter for a class derivated from scikit-learn, implementing inference method and using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_classifier (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a classifier implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_cluster (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a cluster implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_regressor (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a regressor implemented using numpy syntax but executed with ONNX operators.

mlprodict.npy.onnxsklearn_transformer (op_version = None, runtime = None, signature = None, register_class = None, overwrite = True)

Decorator to declare a converter for a transformer implemented using numpy syntax but executed with ONNX operators.

OnnxNumpyCompiler

mlprodict.npy.OnnxNumpyCompiler (self, fct, op_version = None, runtime = None, signature = None, version = None, fctsig = None)

Implements a class which runs onnx graph.

mlprodict.npy.onnx_version.FctVersion (self, args, kwargs)

Identifies a version of a function based on its arguments and its parameters.

as_string (self)

Returns a single stirng identifier.

as_tuple (self)

Returns a single tuple for the version.

as_tuple_with_sep (self, sep)

Returns a single tuple for the version.

OnnxVar

mlprodict.npy.onnx_variable.OnnxVar (self, inputs, op = None, select_output = None, dtype = None, kwargs)

Variables used into onnx computation.

astype (self, dtype)

Cast

copy (self)

Returns a copy of self (use of Identity node).

flatten (self, axis = 0)

Flattens a matrix (see numpy.ndarray.flatten).

not_ (self)

Not.

reshape (self, shape)

Reshape

set_onnx_name (self, name_type)

Forces this variable to get this name during

to_algebra (self, op_version = None)

Converts the variable into an operator.

mlprodict.npy.onnx_variable.MultiOnnxVar (self, inputs, op = None, dtype = None, kwargs)

Class used to return multiple OnnxVar at the same time.

to_algebra (self, op_version = None)

Converts the variable into an operator.

mlprodict.npy.onnx_variable.TupleOnnxAny (self, first, args)

Class used to return multiple OnnxVar at the same time.

add_to (self, scope, container, operator = None, run_converters = False)

Adds outputs to the container if not already added, registered the outputs if the node is not final.

get_output_type_inference (self, input_shapes = None)

Returns the expected output types in a list.

to_onnx (self, args, kwargs)

Converts the underlying class into an ONNX graph.

Registration

mlprodict.npy.update_registered_converter_npy (model, alias, convert_fct, shape_fct = None, overwrite = True, parser = None, options = None)

Registers or updates a converter for a new model so that it can be converted when inserted in a scikit-learn pipeline. This function assumes the converter is written as a function decoarated with onnxsklearn_transformer.

Available functions implemented with ONNX operators

All functions are implemented in two submodules:

ONNX functions executed python ONNX runtime

Same function as above, the import goes from from mlprodict.npy.numpy_onnx_impl import <function-name> to from mlprodict.npy.numpy_onnx_pyrt import <function-name>. These function are usually not used except in unit test or as reference for more complex functions. See the source on github, numpy_onnx_pyrt.py and numpy_onnx_pyrt_skl.py.