Arrays

Dot Array

class pynsn.DotArray(target_area_radius, min_dist_between=None, min_dist_area_boarder=None, xy=None, diameter=None, attributes=None)

Numpy Position list for optimized for numpy calculations

Position + diameter

Parameters

  • target_area_radius (int) –

  • min_dist_between (Optional[int]) –

  • min_dist_area_boarder (Optional[int]) –

  • xy (Optional[Sequence[float]]) –

  • diameter (Optional[Sequence[float]]) –

  • attributes (Optional[Sequence[float]]) –

add(dots)

append one dot or list of dots

Parameters

dots (Union[Dot, Sequence[Dot]]) –

Return type

None

as_dict()
Return type

dict

copy(indices=None, deepcopy=True)

A (deep) copy of the dot array.

It allows to copy a subset of dot only.

Parameters

  • indices (Optional[Sequence[float]]) – Arrays with the indices to be be copied. If None, all object will be copies

  • deepcopy (bool) –

Return type

DotArray

Returns

a copy of the array

csv(variable_names=True, hash_column=False, attribute_column=True)

Comma-separated table representation the object array

Parameters

  • variable_names (bool) – if True first line include the variable names

  • hash_column (bool) – if True hash will be included as first column

  • attribute_column (bool) – if True attributes will be included as last column

Return type

str

Returns

CSV representation

delete(index)

TODO delete object

Parameters

index (Union[int, Sequence[int], ndarray[Any, dtype[int64]]]) –

Returns:

Return type

None

find_objects(diameter=None, attribute=None)

returns indices of found objects

Parameters

  • diameter (Optional[float]) –

  • attribute (Optional[Any]) –

Return type

Sequence[int]

get_center_of_field_area()

Center of all object positions

Return type

ndarray

get_distances(dot)

Euclidean distances toward a single dot

Negative numbers indicate an overlap of the objects

Parameters

dot (Dot) – object towards the distances will be calculated

Returns: numpy array of distances

Return type

ndarray

get_distances_matrix(between_positions=False)

between position ignores the dot size

Parameters

between_positions (bool) –

Return type

ndarray

get_free_position(ref_object, in_neighborhood=False, allow_overlapping=False, inside_convex_hull=False, occupied_space=None)

returns the copy of object of at a random free position

raise exception if not found occupied space: see generator generate

Parameters

  • ref_object (Union[Dot, Rectangle, Point]) –

  • in_neighborhood (bool) –

  • allow_overlapping (bool) –

  • inside_convex_hull (bool) –

Return type

Union[Dot, Rectangle]

get_number_deviant(change_numerosity, preserve_field_area=False)

number deviant

Parameters

  • change_numerosity (int) –

  • preserve_field_area (bool) –

Return type

PointArray

get_outlier()

returns indices of object that stand out and array with the size of outstanding

Return type

Tuple[ndarray, ndarray]

get_overlaps()

return pairs of indices of overlapping of objects and an array of the amount of overlap takes into account min_dist_between property

Return type

Tuple[ndarray, ndarray]

get_split_arrays()

returns a list of _arrays each array contains all dots of with particular colour

Return type

List[PointArray]

iter_objects(indices=None)

iterate over all or a part of the objects

Parameters

indices (int or interable of integer) –

Notes

To iterate all object you might all use the class iterator __iter__: >>> for obj in my_array: >>> print(obj)

Return type

Iterator[Dot]

join(object_array)

add another object _arrays

Return type

None

mod_move_object(object_id, distance, direction, push_other=False)

Move a single object by a particular distance. The function uses direction and direction

Parameters

  • object_id (int) –

  • distance (float) –

  • direction (Union[float, Sequence[float]]) – polar angle (float) or cartesian coordinate (tuple of two floats) to indicate the direction

  • push_other (bool) – replace other objects, if required (optional, default=False)

Return type

None

mod_realign(keep_convex_hull=False, strict=True)
Parameters

  • keep_convex_hull –

  • strict –

Return type

field_area_unchanged, no_outlier

mod_remove_overlaps(keep_convex_hull=False, strict=False)

Returns :type keep_convex_hull: bool :param keep_convex_hull: :type strict: bool :param strict:

Returns

rtn – True, if field area has not been changed (in case strict=False)

Return type

boolean

Notes

TODO describe different algorithm for keep and not keep CH

mod_replace(xy)

Replace the object array

Parameters

xy (Sequence[float]) – replacement at the x and y axis

Return type

None

mod_round_values(decimals=0, int_type=<class 'numpy.int32'>)

Round all values

Parameters

  • decimals (int) – number of decimal places

  • int_type (type) – numpy int type (default=numpy.int16)

Return type

None

mod_shuffle_positions(allow_overlapping=False)

might raise an exception

Parameters

allow_overlapping (bool) –

Return type

None

mod_squeeze_to_area(push_other=True)

Squeeze in target area to remove all standouts

Parameters

push_other (bool) – replace other object, if required to avoid overlaps

Return type

None

static read_from_dict(the_dict)

read Dot collection from dict

Parameters

the_dict (dict) –

Return type

DotArray

set_attributes(attributes)

Set all attributes

Parameters

attributes (Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – attribute (string) or list of attributes

Return type

None

property attributes: ndarray

Numpy vector of the object attributes

Return type

ndarray

property hash: str

Hash (MD5 hash) of the array

The hash can be used as an unique identifier of the object array.

Notes

Hashing is based on the byte representations of the positions, perimeter and attributes.

Return type

str

property perimeter: ndarray

Perimeter for each dot

Return type

ndarray

property properties: ArrayProperties

Properties of the object array.

ArrayProperties represents and handles (fitting, scaling) visual properties of the object like

  • numerosity

  • average_dot_diameter or average_rectangle_size

  • total_surface_area

  • average_surface_area

  • total_perimeter

  • average_perimeter

  • field_area

  • field_area_positions

  • sparsity

  • log_spacing

  • log_size

  • converage

Return type

ArrayProperties

property surface_areas: ndarray

TODO

Return type

ndarray

property xy: ndarray

Numpy array of the object locations

The two dimensional array (shape=[2, n]) represents the locations of the center of the n objects in this array

Return type

ndarray

Rectangle Array

class pynsn.RectangleArray(target_area_radius, min_dist_between=None, min_dist_area_boarder=None, xy=None, sizes=None, attributes=None)
Parameters

  • target_area_radius (int) –

  • min_dist_between (Optional[bool]) –

  • min_dist_area_boarder (Optional[bool]) –

  • xy (Optional[Sequence[float]]) –

  • sizes (Optional[Sequence[float]]) –

  • attributes (Optional[Sequence[float]]) –

add(rectangles)

append one dot or list of dots

Parameters

rectangles (Union[Rectangle, Sequence[Rectangle]]) –

Return type

None

as_dict()

Dict representation of the array

Return type

dict

copy(indices=None, deepcopy=True)

returns a (deep) copy of the dot array.

It allows to copy a subset of dot only.

Parameters

  • indices (Optional[Sequence[float]]) –

  • deepcopy (bool) –

Return type

RectangleArray

csv(variable_names=True, hash_column=False, attribute_column=True)

Comma-separated table representation the object array

Parameters

  • variable_names (bool) – if True first line include the variable names

  • hash_column (bool) – if True hash will be included as first column

  • attribute_column (bool) – if True attributes will be included as last column

Return type

str

Returns

CSV representation

delete(index)

TODO delete object

Parameters

index (Union[int, Sequence[int], ndarray[Any, dtype[int64]]]) –

Returns:

Return type

None

find_objects(size=None, attribute=None, edge=None)

returns indices of found objects

2D-tuple

Parameters

  • size (Union[Tuple[float, float], List[float], ndarray[Any, dtype[float64]], None]) –

  • attribute (Optional[Any]) –

  • edge (Optional[Coordinate]) –

Return type

Sequence[int]

get_center_of_field_area()

Center of all object positions

Return type

ndarray

get_distances(rect)

Euclidean distances toward a single rectangle

Negative numbers indicate an overlap of the objects

Parameters

rect (Rectangle) – object towards the distances will be calculated

Returns: numpy array of distances

Return type

ndarray

get_distances_matrix(between_positions=False)

between position ignores the dot size

Parameters

between_positions (bool) –

Return type

ndarray

get_free_position(ref_object, in_neighborhood=False, allow_overlapping=False, inside_convex_hull=False, occupied_space=None)

returns the copy of object of at a random free position

raise exception if not found occupied space: see generator generate

Parameters

  • ref_object (Union[Dot, Rectangle, Point]) –

  • in_neighborhood (bool) –

  • allow_overlapping (bool) –

  • inside_convex_hull (bool) –

Return type

Union[Dot, Rectangle]

get_number_deviant(change_numerosity, preserve_field_area=False)

number deviant

Parameters

  • change_numerosity (int) –

  • preserve_field_area (bool) –

Return type

PointArray

get_outlier()

returns indices of object that stand out and array with the size of outstanding

Return type

Tuple[ndarray, ndarray]

get_overlaps()

return pairs of indices of overlapping of objects and an array of the amount of overlap takes into account min_dist_between property

Return type

Tuple[ndarray, ndarray]

get_split_arrays()

returns a list of _arrays each array contains all dots of with particular colour

Return type

List[PointArray]

iter_objects(indices=None)

iterate over all or a part of the objects

Parameters

indices (Union[int, Sequence[int], ndarray[Any, dtype[int64]], None]) –

Notes

To iterate all object you might all use the class iterator __iter__: >>> for obj in my_array: >>> print(obj)

Return type

Iterator[Rectangle]

join(object_array)

add another object _arrays

Return type

None

mod_move_object(object_id, distance, direction, push_other=False)

Move a single object by a particular distance. The function uses direction and direction

Parameters

  • object_id (int) –

  • distance (float) –

  • direction (Union[float, Sequence[float]]) – polar angle (float) or cartesian coordinate (tuple of two floats) to indicate the direction

  • push_other (bool) – replace other objects, if required (optional, default=False)

Return type

None

mod_realign(keep_convex_hull=False, strict=True)
Parameters

  • keep_convex_hull –

  • strict –

Return type

field_area_unchanged, no_outlier

mod_remove_overlaps(keep_convex_hull=False, strict=False)

Returns :type keep_convex_hull: bool :param keep_convex_hull: :type strict: bool :param strict:

Returns

rtn – True, if field area has not been changed (in case strict=False)

Return type

boolean

Notes

TODO describe different algorithm for keep and not keep CH

mod_replace(xy)

Replace the object array

Parameters

xy (Sequence[float]) – replacement at the x and y axis

Return type

None

mod_round_values(decimals=0, int_type=<class 'numpy.int16'>)

Round all values

Parameters

  • decimals (int) – number of decimal places

  • int_type (type) – numpy int type (default=numpy.int16)

Return type

None

mod_shuffle_positions(allow_overlapping=False)

might raise an exception

Parameters

allow_overlapping (bool) –

Return type

None

mod_squeeze_to_area(push_other=True)

Squeeze in target area to remove all standouts

Parameters

push_other (bool) – replace other object, if required to avoid overlaps

Return type

None

static read_from_dict(the_dict)

read rectangle array from dict

Parameters

the_dict (dict) –

Return type

RectangleArray

set_attributes(attributes)

Set all attributes

Parameters

attributes (Union[_SupportsArray[dtype], _NestedSequence[_SupportsArray[dtype]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – attribute (string) or list of attributes

Return type

None

property attributes: ndarray

Numpy vector of the object attributes

Return type

ndarray

property hash: str

Hash (MD5 hash) of the array

The hash can be used as an unique identifier of the object array.

Notes

Hashing is based on the byte representations of the positions, perimeter and attributes.

Return type

str

property perimeter: ndarray

Vector with the perimeter of all objects

Return type

ndarray

property properties: ArrayProperties

Properties of the object array.

ArrayProperties represents and handles (fitting, scaling) visual properties of the object like

  • numerosity

  • average_dot_diameter or average_rectangle_size

  • total_surface_area

  • average_surface_area

  • total_perimeter

  • average_perimeter

  • field_area

  • field_area_positions

  • sparsity

  • log_spacing

  • log_size

  • converage

Return type

ArrayProperties

property sizes: ndarray

Numpy array of the object sizes

The two dimensional array (shape=[2, n]) represents the width and height of the n objects in this array

Return type

ndarray

Returns

the width and height

property surface_areas: ndarray

Vector with the surface areas of all objects

Return type

ndarray

property xy: ndarray

Numpy array of the object locations

The two dimensional array (shape=[2, n]) represents the locations of the center of the n objects in this array

Return type

ndarray

Visual properties

class pynsn.ArrayProperties(object_array)
Parameters

object_array (Any) –

as_dict()

ordered dictionary with the most important visual properties

Return type

dict

fit(property_flag, value)

adapt_properties: continuous property or list of continuous properties several properties to be adapted if adapt dot array is specified, array will be adapt to adapt_dot_array, otherwise the values defined in adapt_properties is used. some adapting requires realignement to avoid overlaps. However, realigment might result in a different field area. Thus, realign after adapting for Size parameter and realign before adapting space parameter.

Parameters

  • property_flag (VisualPropertyFlags) –

  • value (float) –

Return type

Any

fit_average_perimeter(value)
Parameters

value (float) –

Return type

None

fit_average_surface_area(value)
Parameters

value (float) –

Return type

None

fit_coverage(value, precision=None, FA2TA_ratio=None)
Parameters

  • value (float) –

  • precision (Optional[float]) –

  • FA2TA_ratio (Optional[float]) –

Return type

None

fit_field_area(value, precision=None)
Parameters

  • value (float) –

  • precision (Optional[float]) –

Return type

None

fit_log_size(value)
Parameters

value (float) –

Return type

None

fit_log_spacing(value, precision=None)
Parameters

  • value (float) –

  • precision (Optional[float]) –

Return type

None

fit_numerosity(value, keep_convex_hull=False)
Parameters

  • value (int) –

  • keep_convex_hull (bool) –

Return type

None

fit_sparcity(value, precision=None)
Parameters

  • value (float) –

  • precision –

Return type

None

fit_total_perimeter(value)
Parameters

value (float) –

Return type

None

fit_total_surface_area(value)
Parameters

value (float) –

Return type

None

get(property_flag)

returns a visual property

Parameters

property_flag (VisualPropertyFlags) –

Return type

Any

reset()

reset to enforce recalculation of certain parameter

Return type

None

property converage: Optional[float]

percent coverage in the field area. It takes thus the object size into account. In contrast, the sparsity is only the ratio of field array and numerosity

Return type

Optional[float]