The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
SPVM-R-0.101
River stage zero No dependents
/ SPVM::R::NDArray

Name

SPVM::R::NDArray - N-Dimensional Array Super Class

Description

R::NDArray class in SPVM represetns n-dimensional array.

This class is the super class of classes of n-dimensional arrays.

Usage

  use R::NDArray;

Details

Column Major Order

Elements of data of n-dimesion array are stored by column major order.

See Row- and column-major order about Row- and column-major order.

Scalar

A scalar is a n-dimensional array for which "is_scalar" method returns a true value.

Vector

A vector is a n-dimensional array for which "is_vector" method returns a true value.

Matrix

A matrix is a n-dimensional array for which "is_matrix" method returns a true value.

Slice of N-Dimensional Array

Slice of n-dimensional array gets subsets of an n-dimensional array given a cartesian product of indexes of each dimension.

Consider the case where the dimensions $dim is [2, 3, 4].

If you gets a subsets at indexes [0, 1] of $dim->[0], indexes [1, 2] of $dim->[1] and [2] of $dim->[2], the cartesian product is [[0, 1], [1, 2], [2]].

The cartesian product is expanded to coordinates.

  [0, 1, 2]
  [1, 1, 2]
  [0, 2, 2]
  [1, 2, 2]

The dimensions of sliced n-dimensional array is [2, 2, 1].

Examples of Slice of N-Dimensional Array

This is an example of slice of n-dimensional array using "slice" method.

  use R::OP::Int as IOP;
  
  my $ndarray = IOP->c(IOP->seq(1, 24), [2, 3, 4]);
  
  my $ret_ndarray = $ndarray->slice([IOP->c([0, 1]), IOP->c([1, 2]), IOP->c([2])]);

$ndarray is

  ,,0
  
       [,0] [,1] [,2]
  [0]    1    3    5
  [1]    2    4    6
  
  ,,1
  
       [,0] [,1] [,2]
  [0]    7    9   11
  [1]    8   10   12
  
  ,,2
  
       [,0] [,1] [,2]
  [0]   13   15   17
  [1]   14   16   18
  
  ,,3
  
       [,0] [,1] [,2]
  [0]   19   21   23
  [1]   20   22   24

$ret_ndarray is

  ,,0

       [,0] [,1]
  [0]   15   17
  [1]   16   18

If you get all indexes of a dimension, you can use undef. This is the same as the avobe example.

  my $ret_ndarray = $ndarray->slice([(R::NDArray::Int)undef, IOP->c([1, 2]), IOP->c([2])]);
  
  # Same also
  my $ret_ndarray = $ndarray->slice([IOP->undef, IOP->c([1, 2]), IOP->c([2])]);

NA Representation

A n-dimensional array in SPVM::R cannot have a real NA element, but the data that represents NA is able to be defined.

Integral types cannot represent NA.

Floating point types represent NA using NaN.

Object types represent NA using undef.

Fields

data

has data : protected ro object;

The array in which the data of the n-dimensional array is stored.

The type of this array is a numeric types, a multi-numeric types, or an object type.

See also "Column Major Order".

dim

has dim : int[];

Dimensions of a n-dimensional array.

dim(getter)

method dim : int[] ();

Creates a new array, copies the dimensions of this n-dimensional array to it, and returns the new array.

dim(setter)

method set_dim : void ($dim : int[]);

The dimensions $dim is normalized by R::Util#normalize_dim method, checks the normalized dim by R::Util#check_length method, and sets this field to the normalized dim.

Exceptions:

If "is_dim_read_only" is a true value, an exception is thrown.

Exceptions thrown by R::Util#normalize_dim method could be thrown.

Exceptions thrown by R::Util#check_length method could be thrown.

is_dim_read_only

has is_dim_read_only : ro byte;

If this field is a true value, it indicates "dim" field is read only, otherwise writable.

Class Methods

normalize_indexes_product

static method normalize_indexes_product : R::NDArray::Int[] ($indexes_product : R::NDArray::Int[], $dim : int[]);

Checks and normalizes the cartesian product of the indexes $indexes_product using the dimensions $dim, and returns it.

If the check failed, an exception is thrown.

Normalization means that

If the length of $indexes_product is less than the length of $dim, $indexes_product is expanded to the length of $dim and expanded elements are set to undef.

The element of $indexes_product at index $i($i is an index of $indexes_product) which value is undef is set to a R::NDArray::Int object which data is the array of consecutive values from 0 to $dim->[$i] - 1.

Exceptions:

The cartesian product of the indexes $indexes_product must be defined.

The dimensions $dim muest be defined. Otherwise an exception is thrown.

The nth element of the cartesian product of the indexes $indexes_product must be a vector or undef.

The n-th element of the data of the m-th element of the cartesian product of the indexes $indexes_product must be less than the k-th element of the dimensions $dim.

The n-th element of the cartesian product of the indexes $indexes_product must be a vector or undef. Otherwise an exception is thrown.

Instance Methods

init

protected method init : void ($options : object[] = undef);

Initialize this n-dimensional array given the options $options.

Options:

  • data : object = undef

    An array that is set to "data" field.

  • dim : int[] = undef

    Dimensions that is set to "dim" field.

Implementation:

dim option is assinged to $dim variable.

data option is assinged to $data variable.

If $data is defined, the data type is checked. The type must be same as the type of an object created by "create_default_data" method.

If $dim is not defined, $dim is created by the length of $data. $dim is set to [length of $data]. If $data is not defined, $dim is set to [].

$dim is normalized by R::Util#normalize_dim method.

If $data is not defined, $data is created by $dim. The data length is calcurated by R::Util#calc_data_length method and "create_default_data" method is called given the data length.

R::Util#check_length method is called to check integrity for $dim and $data.

"data" field is set to $data.

"dim" field is set to $dim.

Exceptions:

If the check of data type failed, an exception is thrown.

Exceptions thrown by R::Util#normalize_dim method could be thrown.

Exceptions thrown by R::Util#check_length method could be thrown.

make_dim_read_only

method make_dim_read_only : void ();

Sets "is_dim_read_only" field to 1.

nrow

method nrow : int ();

Returns the number of rows. This is the value of dimensions at index 0.

this n-dimensional array must be a matrix.

Exceptions:

ncol

method ncol : int ();

this n-dimensional array must be a matrix. Otherwise an exception is thrown.

Returns the number of columns.

If the length of dimensions is greater than or equal to 2, the number of columns is the value of dimensions at index 1, otherwise the number of columns is 1.

this n-dimensional array must be a matrix.

Exceptions:

this n-dimensional array must be a matrix. Otherwise an exception is thrown.

length

method length : int ();

Returns the array length of "data".

is_empty

method is_empty : int ();

If the length of dimensions is equal to 0, returns 1, otherwise returns 0.

is_scalar

method is_scalar : int ();

Checks if this n-dimensional array can be treated as a scalar.

If the length of dimensions is greater than or equal to 1 and the data length calcureated by R::Util#calc_data_length method is 1, returns 1, otherwise return 0.

Examples that return true or false:

  # OK dim
  [1]
  
  [1, 1]
  
  [1, 1, 1]
  
  # Not OK dim
  []
  [2]
  [1, 2]

is_vector

method is_vector : int ();

Checks if this n-dimensional array can be treated as a vector.

If the length of dimensions is greater than or equal to 1 and the value of dimensions at index 0 is the same as the data length calcureated by R::Util#calc_data_length method, returns 1, otherwise return 0.

Examples that return true or false:

  # OK dim
  [1]
  
  [1, 1]
  
  [1, 1, 1]
  
  [2]
  
  [2, 1]
  
  [2, 1, 1]
  
  # Not OK dim
  []
  [2, 2]
  [1, 2]

is_matrix

method is_matrix : int ();

Checks if this n-dimensional array can be treated as a matrix.

Implementation:

$dim : "dim" field.

$dim_length : the length of $dim.

$length : the data length calcureated by R::Util#calc_data_length method.

If $dim_length is not greater than or equal to 1, this method returns 0.

$nrow : numbers of rows. this is $dim at index 0.

$ncol : numbers of columns. If $dim_length is equal to 1, this is 0. Otherwise this is $dim at index 1.

If $nrow multiplied by $ncol is the same as $length, this method returns 1, otherwise returns 0.

Examples that return true or false:

  # OK dim
  [3, 2]
  
  [3, 2, 1]
  
  [2]
  
  [2, 1]
  
  [2, 1, 1]
  
  [1]
  
  [1, 1]
  
  [1, 1, 1]
  
  # Not OK dim
  []
  [1, 1, 3]
  [1, 2, 3]

is_square_matrix

method is_square_matrix : int ();

Checks if this n-dimensional array can be treated as a square matrix.

If this n-dimensional array is a matrix "is_matrix" method returns a true value and the return value of "nrow" is equal to the return value of "ncol", returns 1, otherwise returns 0.

drop_dim

method drop_dim : void ($index : int = -1);

Drops the dimensions of this n-dimensional array by calling R::Util#drop_dim method given the index $index.

Exceptions:

Exceptions thrown by R::Util#drop_dim method could be thrown.

expand_dim

method expand_dim : void ($index : int = -1);

Expands the dimensions of this n-dimensional array by calling R::Util#expand_dim method given the index $index.

Exceptions:

Exceptions thrown by R::Util#expand_dim method could be thrown.

create_default_data

method create_default_data : object ($length : int = 0);

Returns a default data of the length $length.

This method is implemetned in child classes.

Exceptions:

Not implemented.

elem_to_string

method elem_to_string : string ($data : object, $data_index : int);

Converts the element at index $data_index of the array data $data to a string, and returns it.

The returned string must be an element of R::NDArray::String.

This method is called when the "to_string_ndarray" method converts each element to a string. So if an element is undef, this method should return undef.

This method is implemetned in child classes.

Exceptions:

Not implemented.

elem_assign

method elem_assign : void ($dist_data : object, $dist_data_index : int, $src_data : object, $src_data_index : int);

Assigns the element $src_data at index $src_data_index to the element $dist_data at index $dist_data_index.

This method will be implemetned in child classes.

Exceptions:

Not implemented.

elem_clone

method elem_clone : void ($dist_data : object, $dist_data_index : int, $src_data : object, $src_data_index : int);

Clones the element $src_data at index $src_data_index to the element $dist_data at index $dist_data_index.

This method will be implemetned in child classes.

Exceptions:

Not implemented.

elem_cmp

method elem_cmp : int ($a_data : object, $a_data_index : int, $b_data : object, $b_data_index : int);

Compares the element $a_data at index $a_data_index and the element $b_data at index $b_data_index and returns the result.

This method will be implemetned in child classes.

Exceptions:

Not implemented.

elem_is_na

method elem_is_na : int ($data : object, $data_index : int);

Checks if an element represets NA.

See "Na Representation" about NA representation.

This method will be implemented in a child class.

Exceptions:

This method is not implemented.

to_string_ndarray

method to_string_ndarray : R::NDArray::String ();

Converts this n-dimensional array to a n-dimensional array of R::NDArray::String and returns it.

This method calls "elem_to_string" method to convert each element to a string.

elem_size

method elem_size : int ();

Returns the byte size of an element.

elem_type_name

method elem_type_name : string ();

Returns the type name of an element.

is_numeric_ndarray

method is_numeric_ndarray : int ();

If the type of the date of this n-dimensional array is a numeric array, returns 1, otherwise returns 0.

is_mulnum_ndarray

method is_mulnum_ndarray : int ();

If the type of the date of this n-dimensional array is a multi-numeric array, returns 1, otherwise returns 0.

is_any_numeric_ndarray

method is_any_numeric_ndarray : int ();

If the type of the date of this n-dimensional array is a numeric array or a multi-numeric array, returns 1, otherwise returns 0.

is_object_ndarray

method is_object_ndarray : int ();

If the type of the date of this n-dimensional array is an object array, returns 1, otherwise returns 0.

clone

method clone : R::NDArray ($shallow : int = 0);

Clones this n-dimensional array and returns it.

Each element is copied by "elem_clone" method.

If $shallow is a true value, each element is copied by "elem_assign" method.

slice

method slice : R::NDArray ($indexes_product : R::NDArray::Int[]);

Slices this n-dimensional array using the cartesian product of the indexes $indexes_product and returns the sliced n-dimensional array.

See "Slice of N-Dimensional Array" about slice of n-dimensional array.

This method calls "normalize_indexes_product" method to check and normalize $indexes_product.

If you drops the dimensions of a sliced n-dimensioanal array, you can call "drop_dim" method.

Exceptions:

Exceptions thrown by "normalize_indexes_product" method could be thrown.

slice_set

method slice_set : void ($indexes_product : R::NDArray::Int[], $ndarray : R::NDArray);

Slices this n-dimensional array using the cartesian product of the indexes $indexes_product and sets the sliced data to the n-dimensional array $ndarray.

See "Slice of N-Dimensional Array" about slice of n-dimensional array.

This method calls "normalize_indexes_product" method to check and normalize $indexes_product.

Exceptions:

Exceptions thrown by "normalize_indexes_product" method could be thrown.

to_string

method to_string : string ();

Converts this n-dimensional array to a string representation.

order

method order : R::NDArray::Int ();

Creates a R::NDArray::Int object for a return value, sort data in temporary area in ascending order together with its indexes, sets the indexes to the data of the new n-dimensional array, and returns it.

Examples are

  # data
    0,  1,  2  (This is indexes)
  [30, 10, 20]
  
  # Return data
    0,  1,  2  (This is indexes)
  [ 1,  2,  0]

set_order

method set_order : void ($data_indexes_ndarray : R::NDArray::Int);

Sorts the data of this n-dimensional array by the order $data_indexes_ndarray.

Each index in $data_indexes_ndarray specifies an index of the data of this n-dimentional array.

Examples are

  # data
    0,  1,  2  (This is indexes)
  [30, 10, 20]
  
  # $data_indexes_ndarray
  [ 1,  2,  0]
  
  # Ordered data
  [10, 20, 30]

sort_asc

method sort_asc : void ();

Sorts the data of this n-dimension array by ascendant order.

Each two elements are compared by "elem_cmp" method.

This method calls "order" method and "set_order" method to sort the data.

Exceptions:

Exceptions thrown by "order" method and "set_order" method could be thrown.

sort_desc

method sort_desc : void ();

Sorts the data of this n-dimension array by descendant order.

Each two elements are compared by "elem_cmp" method.

This method calls "order" method and "set_order" method to sort the data.

Exceptions:

Exceptions thrown by "order" method and "set_order" method could be thrown.

Well Known Child Classes

See Also

Copyright & License

Copyright (c) 2024 Yuki Kimoto

MIT License