# Typesystem¶

This page describes the data types introduced in pSeven and type conversion rules.

## Introduction¶

pSeven typesystem distinguishes between Boolean, integer, real (floating point) and string values. These values can be scalar, vector, or matrix. As a result of taking all possible combinations, there are 12 base types: BoolScalar, IntScalar, RealScalar, StringScalar and so on for vectors and matrices (for example, RealVector, StringMatrix).

Special types are File (file object), Blob (arbitrary binary data), List and Dict (pSeven implementation of heterogeneous list and associative array types). List and Dict are heterogeneous containers — they allow mixing elements of different types and can hold elements of any base or special type.

Lastly, there is the Undefined type (which actually is a special value, like None in Python).

In total, there are 17 typenames (12 base, 4 special, and Undefined). Detailed information on individual types (including their standard string representations used here) can be found in the pSeven Data Types reference. This page describes pSeven typesystem concepts and type conversion rules in general.

## Base Types¶

Base pSeven data types can represent:

Boolean values are either True or False, other representations are not supported.

Integer values are 32-bit signed integers, floating point numbers are double precision floats, represented by numeric literals.

String literals are always enclosed in double quotes.

Vectors and matrices are homogeneous: all elements are of the same type. All indices are zero-based. Matrices are indexed in row major order. String form also follows this order: for example, in the ((11, 12), (21, 22)) matrix, (11, 12) and (21, 22) are matrix rows.

## Special Types¶

Special data types can be used to represent:

• A mixed data collection (List).
• A set of named values of different types (Dict).
• An existing file, or a file that has to be created in a specified place, or a temporary file (File).
• Arbitrary byte sequence, binary data (Blob).

List is an heterogeneous ordered sequence: elements may have different types and are addressed by index. An element may have any base or special type. Indices are zero-based.

Dict is an heterogeneous associative (unordered) array containing key-value pairs. Values may have different types and are addressed by keys. A value may have any base or special type. Keys may be strings only.

File is an advanced type for file handling (a file-like object). It is used to pass control over files between blocks. For details on File properties, see the File block page.

Blob is raw binary data. This type is introduced to support Python bytearray type.

## Conversion Rules¶

Two cases have to be considered to understand data type conversion in pSeven. The first is when data is converted between pSeven types — for example, it travels through a link connecting two block ports with different types. The second is conversion between a pSeven type and a native Python type. It occurs, for example, in blocks that support Python scripting. When a value received to port is assigned to a script variable, it is converted from a pSeven type to a Python type. When the block reads a value of a script variable in order to output it to a port, this value is converted from a Python type to a pSeven type.

### pSeven Types Conversion¶

pSeven allows conversion of base data types to each other, if it does not lead to data loss:

• Scalars can be converted to vectors and matrices (naturally, the result contains a single element).
• Vectors can be converted to single-row matrices. Also, a vector can be converted to a scalar, but only if the vector contains a single element.
• Matrices can be converted to vectors if they contain a single row or a single column, and to scalars if they contain a single element.
• “Inner” type conversion is possible according to the following order: Boolean, integer, real, string.

For example, a single-element IntMatrix can be converted to a RealScalar (((42)) to 42.0), but not to a BoolMatrix because the value of 42 will be lost. A single-column RealMatrix can be converted to a StringVector (((1.0), (2.0), (3.0)) to ("1.0", "2.0", "3.0")) or RealVector, but not to a StringScalar because it cannot describe the structure.

Warning

Converting floating point numbers to strings reduces precision.

In some situations there are two or more possible conversions. For example, a link may connect an output port of IntVector type with an input port that accepts both IntMatrix and RealVector. In such cases the preferred conversion is selected in the following order: BoolScalar, BoolVector, BoolMatrix, IntScalar, IntVector, IntMatrix, RealScalar, RealVector, RealMatrix, StringScalar, StringVector, StringMatrix. So the integer vector in the example above is converted to an integer matrix with a single row.

All base data types can also be converted to List. A scalar becomes a List with a single element, a vector becomes a List of scalars, and a matrix is split by rows and becomes a list of lists.

A homogeneous flat List (a list containing only scalar values of the same type) can be converted to a vector — for example, [1.0, 2.0, 3.0] to RealVector (1.0, 2.0, 3.0). Such lists can also be directly converted to single-row matrices.

Similarly, a List can be converted to a matrix if it contains only vectors of the same dimension or contains nested List values that can be converted to such vectors. That is, if the List can be interpreted as a rectangular matrix, it can be converted to a matrix. For example, a List of integer vectors [(1, 2), (3, 4)] can be converted to IntMatrix ((1, 2), (3, 4)), as can be a List of equally sized lists of integers [[1, 2], [3, 4]]. A List of floating point values can also contain Undefined, which will be converted to a NaN value.

If a List can be converted to a vector or matrix with a single element, this List can also be converted to a scalar: for example, [1.0] to 1.0, or [["abc"]] to "abc".

Dict, File, and Blob can not be converted to or from any other type. Undefined can be converted to RealScalar, the resulting value will be NaN.

pSeven type descriptions in the pSeven Data Types reference include allowed conversions between pSeven data types.

### Python to pSeven Types Conversion¶

pSeven supports bool, int and float Python types, None values, str, unicode, list, tuple and bytearray sequences, dict and numpy.ndarray.

When converting from Python to pSeven types, Boolean, numeric, and string values by default are converted to appropriate scalars: bool to BoolScalar, int to IntScalar (long is not supported), float to RealScalar, str and unicode to StringScalar. It is also possible to force converting them to a vector or matrix type.

Flat list or tuple is by default converted to an appropriate vector type, provided that:

• all elements are of the same type, and
• this type is bool, int, float, str, or unicode.

A list or tuple like this can also be forcibly converted to a single-row matrix.

Nested list or tuple is by default converted to a nested List, and can be forcibly converted to a matrix, provided that:

• the top level contains only lists and/or tuples,
• nesting level is 1,
• all nested lists (tuples) are of the same length,
• all elements of the nested lists (tuples) are of the same type, and
• this type is bool, int, float, str, or unicode.

Other tuples and lists (containing different types, or with various nesting levels) can be converted to List only. Contained types must be supported by pSeven (for example, a List of complex numbers is not possible).

When there are two or more possible conversions from a Python to a pSeven type, the rule is the same as for pSeven types (see section pSeven Types Conversion). For example, if an int value has to be output to a port that allows IntVector and RealScalar, it is converted to IntVector with a single element because or the preferred conversion order (from BoolScalar to StringMatrix, see above). Note that the result of conversion is not RealScalar despite logically the original value is scalar. In case a list or tuple is output to a port with multiple types, pSeven again tries preferred conversions or, if they all fail, tries converting to List. A few examples of list conversion are:

• [True, False, True] to BoolVector (true, false, true).
• [[1, 2, 3], [3, 2, 1]] to IntMatrix ((1, 2, 3), (3, 2, 1)).
• ['string'] to StringVector ("string").
• [1, [21, 22]] to List [1, [21, 22]] (elements are IntScalar).
• [True, 1.0] to List [true, 1.0] (elements are BoolScalar and RealScalar).
• [2, None, 3] to RealVector (2.0, NaN, 3.0).

Python bytearray is converted to Blob by default.

Dictionaries (dict) are converted to Dict; in this case, keys will be converted to strings.

None is always converted to Undefined.

An N-dimensional array (numpy.ndarray) of values of the same type is by default converted to vector, if N = 1 and to matrix, if N = 2 (1-dimensional array can be forcibly converted to a single-row matrix). It is better to use numpy.ndarray for Xvector and Xmatrix values to enhance the performance, especially in case of big data. Any other numpy.ndarray is converted to List (note that array elements must be of a supported type).

pSeven type descriptions in the pSeven Data Types reference include Python equivalents to pSeven types. For a Python type, being equivalent to a pSeven type means that this Python type is converted to this pSeven type by default (that is, if conversion is not restricted by a port type or other means).

### pSeven to Python Types Conversion¶

Rules of conversion from pSeven to Python types are the most strict compared to conversion between pSeven types or from Python to pSeven types. This conversion is controlled by pSeven, and there is no way to force convert some pSeven type to a non-default Python type.

• BoolScalar, IntScalar, RealScalar, and StringScalar are converted to bool, int, float and unicode respectively.
• A vector type is converted to 1-dimensional numpy.ndarray. This array contains values converted from pSeven scalar type to Python type (see above).
• A matrix type is converted to 2-dimensional numpy.ndarray. This array contains values converted from pSeven scalar type to Python type (see above).
• List is converted to list. List elements are converted following the rules for their types.
• Dict is converted to dict. Dict keys are converted to unicode (as they are originally StringScalar). Dict values are converted following the rules for their types.
• Blob is converted to bytearray.
• File cannot be converted to a Python file-like object or another type directly.
• Undefined is converted to None.

pSeven type descriptions in the pSeven Data Types reference include Python equivalents to pSeven types. Considering pSeven to Python types conversion, the Python equivalent is the resulting type.

## Reference¶

This reference provides summary information on the data types introduced in pSeven, their string representations (usable in data editors), value ranges, equivalent Python types and supported conversions between pSeven types.

### pSeven Data Types¶

#### Typenames¶

In total, there are 17 typenames in pSeven. The type naming rules are described on the Typesystem page.

#### Scalar Types¶

Boolean scalar

Boolean value, True or False.

Typename: BoolScalar Boolean literal — True, False N/A from pSeven types: BoolVector and BoolMatrix containing a single element; List containing a single BoolScalar to pSeven types: any scalar, vector or matrix type; List equivalent Python type: bool

Integer scalar

Single integer value.

Typename: IntScalar numeric literal, signed decimal integer — 42, -20 32-bit integer range from pSeven types: BoolScalar; BoolVector, IntVector, BoolMatrix and IntMatrix containing a single element; List containing a single IntScalar to pSeven types: RealScalar, StringScalar; IntVector, RealVector, StringVector; IntMatrix, RealMatrix, StringMatrix; List equivalent Python type: int

Real scalar

Single floating point value.

Typename: RealScalar numeric literal, signed decimal float in fixed-point notation — 42., -48.5 double-precision floating point range from pSeven types: BoolScalar, IntScalar; BoolVector, IntVector, RealVector, BoolMatrix, IntMatrix and RealMatrix containing a single element; List containing a single RealScalar to pSeven types: StringScalar; RealVector, StringVector; RealMatrix, StringMatrix; List equivalent Python type: float

String scalar

Unicode character string.

Typename: StringScalar string literal in double quotes — "string" N/A from pSeven types: any scalar type; any vector or matrix type if they contain a single element; List containing a single StringScalar to pSeven types: StringVector; StringMatrix; List equivalent Python type: unicode

#### Vector Types¶

Boolean vector

Flat array of Boolean values.

Typename: BoolVector comma-delimited list of Boolean values enclosed in parentheses — (true, false, true) N/A from pSeven types: BoolScalar; BoolMatrix containing a single row or column; flat List containing only BoolScalar values to pSeven types: any scalar type if the vector contains a single element; any vector or matrix type; List equivalent Python type: numpy.ndarray (1D, dtype=bool)

Integer vector

Flat array of integer values.

Typename: IntVector comma-delimited list of integers enclosed in parentheses — (1, -2, 3) 32-bit integer range from pSeven types: BoolScalar, IntScalar; BoolVector; BoolMatrix and IntMatrix containing a single row or column; flat List containing only IntScalar values to pSeven types: IntScalar, RealScalar, StringScalar if the vector contains a single element; RealVector, StringVector; IntMatrix, RealMatrix, StringMatrix; List equivalent Python type: numpy.ndarray (1D, dtype=int32)

Real vector

Flat array of floating point values.

Typename: RealVector comma-delimited list of floating point values enclosed in parentheses — (0.5, -1.2) double-precision floating point range (for each component) from pSeven types: BoolScalar, IntScalar, RealScalar; BoolVector, IntVector; BoolMatrix, IntMatrix, and RealMatrix containing a single row or column; flat List containing only RealScalar values to pSeven types: RealScalar, StringScalar if the vector contains a single element; StringVector; RealMatrix, StringMatrix; List equivalent Python type: numpy.ndarray (1D, dtype=float64)

String vector

Flat array of character strings.

Typename: StringVector comma-delimited list of strings in double quotes, enclosed in parentheses — ("foo", "bar") N/A from pSeven types: any scalar or vector type; any matrix type if the matrix contains a single row or column; flat List containing only StringScalar values to pSeven types: StringScalar if the vector contains a single element; StringMatrix; List equivalent Python type: numpy.ndarray (1D, dtype=’

#### Matrix Types¶

Boolean matrix

2D array of Boolean values.

Typename: BoolMatrix list of equally long lists of Boolean values, all lists are comma-delimited and enclosed in parentheses — ((true, false), (false, true)) N/A from pSeven types: BoolScalar; BoolVector; List containing BoolVector values of the same dimension, List containing equally long lists of BoolScalar values to pSeven types: any scalar type if the matrix contains a single element; any vector type if the matrix contains a single row or column; any matrix type; List equivalent Python type: numpy.ndarray (2D, dtype=bool)

Integer matrix

2D array of integer values.

Typename: IntMatrix list of equally long lists of integers, all lists are comma-delimited and enclosed in parentheses — ((11, 12), (21, 22)) 32-bit integer range from pSeven types: BoolScalar, IntScalar; BoolVector, IntVector; BoolMatrix; List containing IntVector values of the same dimension, List containing equally long lists of IntScalar values to pSeven types: IntScalar, RealScalar, StringScalar if the matrix contains a single element; IntVector, RealVector, StringVector if the matrix contains a single row or column; RealMatrix, StringMatrix; List equivalent Python type: numpy.ndarray (2D, dtype=int32)

Real matrix

2D array of floating point values.

Typename: RealMatrix list of equally long lists of floating point values, all lists are comma-delimited and enclosed in parentheses — ((1.1, 1.2), (2.1, 2.2)) double-precision floating point range from pSeven types: BoolScalar, IntScalar, RealScalar; BoolVector, IntVector, RealVector; BoolMatrix, IntMatrix; List containing RealVector values of the same dimension, List containing equally long lists of RealScalar values to pSeven types: RealScalar, StringScalar if the matrix contains a single element; RealVector, StringVector if the matrix contains a single row or column; StringMatrix; List equivalent Python type: numpy.ndarray (2D, dtype=float64)

String matrix

2D array of character strings.

Typename: StringMatrix list of equally long lists of strings, all lists are comma-delimited and enclosed in parentheses — (("a", "b"), ("c", "d")) N/A from pSeven types: any scalar, vector or matrix type; List containing StringVector values of the same dimension, List containing equally long lists of StringScalar values to pSeven types: StringScalar if the matrix contains a single element; StringVector if the matrix contains a single row or column; List equivalent Python type: numpy.ndarray (2D, dtype=’

#### Containers¶

List

Heterogeneous list.

Typename: List comma-delimited list of arbitrary elements (in their own string representations), enclosed in square brackets — [0.5, true, ("foo", "bar"), ((11, 12), (21, 22))] N/A from pSeven types: trivial conversion from scalar type; intelligent conversion from vector and matrix types (results in a List which can be converted back to the original type) to pSeven types: any scalar type if the list contains a single element of that type; any vector type if the list contains only appropriate scalar values (that is, the list is homogeneous and does not contain arrays or nested lists, so it can be interpreted as a vector); corresponding matrix type if the list can be converted to a vector according to the above rule (that is, a vector-like list can be interpreted as a single-row matrix); any matrix type if the list contains only appropriate vector values of the same dimension or only equally long lists that can be converted to the same vector type (that is, the list can be interpreted as a rectangular matrix) equivalent Python type: list

Dict

Associative array of key-value pairs. Keys can be strings only. Values can be of scalar, vector, matrix, List, or Dict type.

Typename: Dict comma-delimited list of key-value pairs, enclosed in curly brackets; keys are strings in double quotes, values use their own string representations; a key is separated from its value by a colon — {"key_list": ["a", [1, 2, 3], false], "key_int": 42, "key_realmatrix": ((1.1, 1.2), (2.1, 2.2))} N/A from pSeven types: none to pSeven types: none equivalent Python type: dict with the limitation that keys have to be of unicode or str type, and values must allow conversion to scalar, vector, matrix, List, or Dict types

#### Special Types¶

Binary data

Arbitrary binary data.

Typename: Blob hexadecimal string with the 0x prefix — 0x4D7956616C7565 N/A from pSeven types: none to pSeven types: none equivalent Python type: bytearray

File

File-like object.

Typename: File special string of the form origin_prefix:file_path, where origin_prefix can be temporary, sandbox, or project (see File Origin), and file_path is an absolute or relative path — project:ProjectSubdirectory\myfile.dat, temporary:C:\Temp\p7tempfile N/A from pSeven types: none to pSeven types: none equivalent Python type: none (can not be directly converted to or from a Python file-like object); when accessed from a script in a scripting block, a variable of this type is an object that mimics a Python’s file-like and provides similar common methods

Undefined

Denotes a lack of value, such as an unassigned variable. It rather is a special value valid for any type, than an actual data type; thus it is not possible to create a variable or port of Undefined type. Also, all Python types that can not be properly converted to a pSeven type become Undefined.

Typename: Undefined empty string N/A from pSeven types: N/A to pSeven types: RealScalar equivalent Python type: None