numgo

package module
v0.0.0-...-b9dc613 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 8, 2017 License: BSD-3-Clause Imports: 9 Imported by: 0

README

numgo GoDoc Build Status Go Report Card codecov.io

An n-dimensional array package implemented in Go.

Note: Under heavy development. API will not stabilize until v0.1 tag.

Installation

go get github.com/Kunde21/numgo

Using numgo

Most of the functionality resembles numpy's API, with some changes to work with Go's type system.

var array := numgo.NewArray64(nil,/*array shape*/1,2,3)	// This will be filled with zeros by default
var arange := numgo.Arange(100)                         // Simple 1-D array filled with incrementing numbers
arange.Reshape(2,5,10)                                  // Changes the shape from 1-D to 3-D
arange.Mean(2)                                          // Mean across axis 2, returning a 2-D (2x5) array
arange.Sum()                                            // An empty call operates over all data on all axes

Any formula can be created and mapped onto one or more axes within the array:

	// Create a FoldFunc
	countNaNFn := func(input []float64) float64 {
	   var i float64 :=0
	       for _,v := range input {
	       	       if math.IsNaN(v) {
				i++
			}
		}
		return i
	}

	// Pass it into the Fold method and give it any number of axes to fold over

	// Returns an n-dimensional array object 
	// with the count of NaN values on 2nd and 4th axes. (0-based axis count)
	array.Fold(countNaNFn, 2,4) 
	// No axes operates over all data on all axes
	array.Fold(countNanfn)

Function chaining

numgo is designed to allow chaining of functions, to allow different actions on different axes and at different points in the calculation. Errors are maintained by the object and can be checked and handled using HasErr() or GetErr():

	// Errors are not handled on each call, 
	// but, instead, can be checked and handled after a block of calculations
	ng := numgo.Arange(100).Reshape(2,5,10).Mean(2).Min(1).Max()
	
	// Non-allocating style
	if ng.HasErr() {
	   log.Println(ng.GetErr())  // GetErr() clears the error flag
	 }
	   
	 // Allocation style
	if err = ng.GetErr(); err != nil {  
		log.Println(err)
	}
	// ng.GetErr() will always return nil here, 
	// so avoid stacking this type of error handling 

Debugging option

Debugging can be enabled by calling numgo.Debug(true). This will give detailed error strings and stack traces by using GetDebug() instead of GetErr(). This makes debugging chained method calls much easier.

	numgo.Debug(true)
	nilp := new(Array64)		// Forgot to inintialize the array.
	
	nilp.Set(12, 1,4,0).AddC(2).DivC(6).At(1,4,0)
	if nilp.HasErr(){
		err, debug, trace := nilp.GetDebug()
		// Prints generic error: "Nil pointer received."
		fmt.Println(err)
		// Prints debug info: "Nil pointer received by GetDebug().  Source array was not initialized."
		fmt.Println(debug)
		// Prints stack trace for the call to GetDebug()
		fmt.Println(trace)
	}

	resz := NewArray64(nil, 2, 5)   // 2-D (2x5) array of zeros
	
	// Reshape would change the capacity of the array, which should use Resize
	resz.AddC(10).DivC(2).Reshape(3,3).Mean(1)  

	if resz.HasErr() {
	   	err, debug, trace := resz.GetDebug()
		// Prints generic error: "New shape cannot change the size of the array."
		fmt.Println(err)
		// Prints debug info: "Reshape() cannot change data size.  Dimensions: [2,5] reshape: [3,3]"
		fmt.Println(debug)
		// Prints stack trace for the call to Reshape()
		fmt.Println(trace)
	}

Contributions

If you have any suggestions, corrections, bug reports, or design ideas please create an issue so that we can discuss and improve the code.

Documentation

Overview

Package numgo provides implementations of n-dimensional array objects and operations.

Two types of numgo arrays are currently supported: Array64 holds float64 values Arrayb holds boolean values

Basic usage

Array64 objects can be created from a slice or as an empty array. Arange and Identity are convenience creation functions.

array := numgo.NewArray64(nil,1,2,3)  // This 1x2x3 array will be filled with zeros by default

sl := []float64{2,2,3,3,4,4}
wrap := numgo.NewArray64(sl)          // Wrap a copy of the slice as a 1-D Array64
wrap2 := numgo.NewArray64(sl,3,2)     // Wrap a copy of the slice as a 3x2 Array64
wrap3 := numgo.NewArray64(sl,2,2)     // Only wraps the first 4 values in sl as a 2x2 Array64

arange := numgo.Arange(100)           // Simple 1-D array filled with incrementing numbers
arange.Reshape(2,5,10)                // Changes the shape from 1-D to 3-D
arange.Mean(2)                        // Mean across axis 2, returning a 2-D (2x5) array
arange.Sum()                          // An empty call operates on all data (Grand Total)

Fold and Map operations

Map takes a function of type MapFunc and applies it across all data elements. Fold and FoldCC take a function of type FoldFunc and applies it in contracting the data across one or more axes.

// Increment MapFunc definition
increment := func(input float64) float64 {
       return input + 1
}
array.Map(increment)  // Using map with defined function
array.AddC(1)   // Using built-in add method

// Create a FoldFunc
   sumFn := func(input []float64) float64 {
       var t float64 :=0
       for _,v := range input {
           t += v
       }
       return t
   }

// Pass it into the Map method and give it any number of axes to map over

// Returns an n-dimensional array object
// with the count of NaN values on 2nd and 4th axes. (0-based axis count)
array.Fold(sumFn, 2,4)

// No axes operates over all data on all axes
array.Fold(sumfn)

Function Chaining

numgo is designed with function-chaining at its core, to allow different actions on different axes and at different points in the calculation. Errors are maintained by the object and can be checked and handled using HasErr() and GetErr():

// Errors are not handled on each call,
// but, instead, can be checked and handled after a block of calculations
ng := numgo.Arange(100).Reshape(2,5,10).Mean(2).Min(1).Max()

// Non-allocating style
if ng.HasErr() {
    log.Println(ng.GetErr())  // GetErr() clears the error flag
}

// Allocation style
if err = ng.GetErr(); err != nil {
    log.Println(err)
}
// ng.GetErr() will always return nil here,
// so avoid stacking this type of error handling

Debugging options

Debugging can be enabled by calling numgo.Debug(true). This will give detailed error strings by using GetDebug() instead of GetErr(). This makes debugging chained method calls much easier.

 numgo.Debug(true)
 nilp := new(Array64)     // Forgot to initialize the array.

 nilp.Set(12, 1,4,0).AddC(2).DivC(6).At(1,4,0)
 if nilp.HasErr(){
     err, debug, trace := nilp.GetDebug()

     // Prints generic error: "Nil pointer received."
     fmt.Println(err)

     // Prints debug info:
     // "Nil pointer received by GetDebug().  Source array was not initialized."
     fmt.Println(debug)

     // Prints stack trace for the call to GetDebug()
     fmt.Println(trace)
 }

 resz := NewArray64(nil, 2, 5)   // 2-D (2x5) array of zeros

 // Reshape would change the capacity of the array, which should use Resize
 resz.AddC(10).DivC(2).Reshape(3,3).Mean(1)

 if resz.HasErr() {
    	err, debug, trace := resz.GetDebug()
	// Prints generic error: "New shape cannot change the size of the array."
	fmt.Println(err)
	// Prints debug info:
        // "Reshape() cannot change data size.  Dimensions: [2,5] reshape: [3,3]"
	fmt.Println(debug)
	// Prints stack trace for the call to Reshape()
	fmt.Println(trace)
 }

Index

Constants

This section is empty.

Variables

View Source
var (
	// NilError flags any error where a nil pointer is received
	NilError = &ngError{"NilError: Nil pointer recieved."}
	// ShapeError flags any mismatching
	ShapeError = &ngError{"ShapeError: Array shapes don't match and can't be broadcast."}
	// ReshapeError flags incorrect use of Reshape() calls.
	// Resize() is the only call that can change the capacity of arrays.
	ReshapeError = &ngError{"ReshapeError: New shape cannot change the size of the array."}
	// NegativeAxis is forNew/Reshape/Resize calls with negative axis length: not allowed
	NegativeAxis = &ngError{"NegativeAxis: Negative axis length received."}
	// IndexError flags any attempt to index out of range
	IndexError = &ngError{"IndexError: Index or Axis out of range."}
	// InvIndexError flags Negative or illegal indexes
	InvIndexError = &ngError{"InvIndexError: Invalid or illegal index received."}
	// FoldMapError catches panics within Fold/FoldCC/Map calls.
	// This will store the panic message in the debug string
	// when debugging is turned off, for proper errror reporting
	FoldMapError = &ngError{"FoldMapError: Fold/Map function panic encountered."}
)

Functions

func Debug

func Debug(set bool) bool

Debug sets the error reporting level for the library. To get debugging data from the library, set this to true and use GetDebug() in place of GetErr().

Debugging information includes the function call that generated the error, stack trace at the point the error was generated, and the values involved in that function call. This will add overhead to error reporting and handling, so use it for development and debugging purposes.

Types

type Array64

type Array64 struct {
	// contains filtered or unexported fields
}

Array64 is an n-dimensional array of float64 data

func Arange

func Arange(vals ...float64) (a *Array64)

Arange Creates an array in one of three different ways, depending on input:

Arange(stop):              Array64 from zero to positive value or negative value to zero
Arange(start, stop):       Array64 from start to stop, with increment of 1 or -1, depending on inputs
Arange(start, stop, step): Array64 from start to stop, with increment of step

Any inputs beyond three values are ignored

func FullArray64

func FullArray64(val float64, shape ...int) (a *Array64)

FullArray64 creates an Array64 object with dimensions given in order from outer-most to inner-most All elements will be set to the value passed in val.

func Identity

func Identity(size int) (r *Array64)

Identity creates a size x size matrix with 1's on the main diagonal. All other values will be zero.

Negative size values will generate an error and return a nil value.

func MaxSet

func MaxSet(arrSet ...*Array64) (b *Array64)

MaxSet will return the element-wise maximum of arrays.

All arrays must be the non-nil and the same shape.

func MinSet

func MinSet(arrSet ...*Array64) (b *Array64)

MinSet will return the element-wise maximum of arrays.

All arrays must be the non-nil and the same shape.

func NewArray64

func NewArray64(data []float64, shape ...int) (a *Array64)

NewArray64 creates an Array64 object with dimensions given in order from outer-most to inner-most Passing a slice with no shape data will wrap the slice as a 1-D array. All values will default to zero. Passing nil as the data parameter creates an empty array.

func RandArray64

func RandArray64(base, scale float64, shape ...int) (a *Array64)

RandArray64 creates an Arry64 object and fills it with random values from the default random source Use base and scale to adjust the default value range [0.0, 1.0) generated by formula rand * scale + default

func (*Array64) Add

func (a *Array64) Add(b *Array64) *Array64

Add performs element-wise addition Arrays must be the same size or able to broadcast. This will modify the source array.

func (*Array64) AddC

func (a *Array64) AddC(b float64) *Array64

AddC adds a constant to all elements of the array.

func (*Array64) Append

func (a *Array64) Append(val *Array64, axis int) *Array64

Append will concatenate a and val at the given axis.

Source array will be changed, so use C() if the original data is needed. All axes must be the same except the appending axis.

func (*Array64) At

func (a *Array64) At(index ...int) float64

At returns the element at the given index. There should be one index per axis. Generates a ShapeError if incorrect index.

func (*Array64) C

func (a *Array64) C() (b *Array64)

C will return a deep copy of the source array.

func (*Array64) Count

func (a *Array64) Count(axis ...int) *Array64

Count gives the number of elements along a set of axis. Value in the element is not tested, all elements are counted.

func (*Array64) Div

func (a *Array64) Div(b *Array64) *Array64

Div performs element-wise division Arrays must be the same size or able to broadcast. Division by zero conforms to IEEE 754 0/0 = NaN, +x/0 = +Inf, -x/0 = -Inf This will modify the source array.

func (*Array64) DivC

func (a *Array64) DivC(b float64) *Array64

DivC divides all elements of the array by a constant. Division by zero conforms to IEEE 754 0/0 = NaN, +x/0 = +Inf, -x/0 = -Inf

func (*Array64) DotProd

func (a *Array64) DotProd(b *Array64) *Array64

DotProd calculates the dot (scalar) product of two vectors. NOTE: Only implemented on 1-D arrays, and other sizes are NOOP

func (*Array64) Equals

func (a *Array64) Equals(b *Array64) (r *Arrayb)

Equals performs boolean '==' element-wise comparison

func (*Array64) FMA12

func (a *Array64) FMA12(x float64, b *Array64) *Array64

FMA12 is the fuse multiply add functionality. Array x will contain a[i] = x*a[i]+b[i]

func (*Array64) FMA21

func (a *Array64) FMA21(x float64, b *Array64) *Array64

FMA21 is the fuse multiply add functionality. Array x will contain a[i] = a[i]*b[i]+x

func (*Array64) Flatten

func (a *Array64) Flatten() *Array64

Flatten reshapes the data to a 1-D array.

func (*Array64) Fold

func (a *Array64) Fold(f FoldFunc, axis ...int) (ret *Array64)

Fold applies function f along the given axes. Slice containing all data to be consolidated into an element will be passed to f. Return value will be the resulting element's value.

func (*Array64) FoldCC

func (a *Array64) FoldCC(f FoldFunc, axis ...int) (ret *Array64)

FoldCC applies function f along the given axes concurrently. Each call to f will launch a goroutine. In order to leverage this concurrency, MapCC should only be used for complex and CPU-heavy functions.

Simple functions should use Fold(f, axes...), as it's more performant on small functions.

func (*Array64) GetDebug

func (a *Array64) GetDebug() (err error, debugStr, stackTrace string)

GetDebug returns and clears the error object from the array object. The returned debug string will include the function that generated the error and the arguments that caused it.

This debug information will only be generated and returned if numgo.Debug is set to true before the function call that causes the error.

func (*Array64) GetErr

func (a *Array64) GetErr() (err error)

GetErr returns the error object and clears the error from the array.

This will only return an error value once per error instance. Do not use it in the if statement to test for the existence of an error. HasErr() is provided for that purpose.

func (*Array64) Greater

func (a *Array64) Greater(b *Array64) (r *Arrayb)

Greater performs boolean '<' element-wise comparison

func (*Array64) GreaterEq

func (a *Array64) GreaterEq(b *Array64) (r *Arrayb)

GreaterEq performs boolean '<=' element-wise comparison

func (*Array64) HasErr

func (a *Array64) HasErr() bool

HasErr tests for the existence of an error on the Array64 object.

Errors will be maintained through a chain of function calls, so only the first error will be returned when GetErr() is called. Use HasErr() as a gate for the GetErr() or GetDebug() choice in error handling code.

func (*Array64) Less

func (a *Array64) Less(b *Array64) (r *Arrayb)

Less performs boolean '<' element-wise comparison

func (*Array64) LessEq

func (a *Array64) LessEq(b *Array64) (r *Arrayb)

LessEq performs boolean '<=' element-wise comparison

func (*Array64) Map

func (a *Array64) Map(f MapFunc) (ret *Array64)

Map applies function f to each element in the array.

func (*Array64) MarshalJSON

func (a *Array64) MarshalJSON() ([]byte, error)

MarshalJSON fulfills the json.Marshaler Interface for encoding data. Custom Unmarshaler is needed to encode/send unexported values.

func (*Array64) MatProd

func (a *Array64) MatProd(b *Array64) *Array64

func (*Array64) Max

func (a *Array64) Max(axis ...int) (r *Array64)

Max will return the maximum along the given axes.

func (*Array64) Mean

func (a *Array64) Mean(axis ...int) *Array64

Mean calculates the mean across the given axes. NaN values in the dataa will result in NaN result elements.

func (*Array64) Min

func (a *Array64) Min(axis ...int) (r *Array64)

Min will return the minimum along the given axes.

func (*Array64) Mult

func (a *Array64) Mult(b *Array64) *Array64

Mult performs element-wise multiplication. Arrays must be the same size or able to broadcast. This will modify the source array.

func (*Array64) MultC

func (a *Array64) MultC(b float64) *Array64

MultC multiplies all elements of the array by a constant.

func (*Array64) NaNCount

func (a *Array64) NaNCount(axis ...int) *Array64

NaNCount calculates the number of values along a given axes. Empty call gives the total number of elements.

func (*Array64) NaNMean

func (a *Array64) NaNMean(axis ...int) *Array64

NaNMean calculates the mean across the given axes. NaN values are ignored in this calculation.

func (*Array64) NaNSum

func (a *Array64) NaNSum(axis ...int) *Array64

NaNSum calculates the sum result array along a given axes. All NaN values will be ignored in the Sum calculation. If all element values along the axis are NaN, NaN is in the return element.

Empty call gives the grand sum of all elements.

func (*Array64) Nonzero

func (a *Array64) Nonzero(axis ...int) *Array64

Nonzero counts the number of non-zero elements in the array

func (*Array64) NotEq

func (a *Array64) NotEq(b *Array64) (r *Arrayb)

NotEq performs boolean '1=' element-wise comparison

func (*Array64) Pow

func (a *Array64) Pow(b *Array64) *Array64

Pow raises elements of a to the corresponding power in b. Arrays must be the same size or able to broadcast. This will modify the source array.

func (*Array64) PowC

func (a *Array64) PowC(b float64) *Array64

PowC raises all elements to a constant power. Negative powers will result in a math.NaN() values.

func (*Array64) Reshape

func (a *Array64) Reshape(shape ...int) *Array64

Reshape Changes the size of the array axes. Values are not changed or moved. This must not change the size of the array. Incorrect dimensions will return a nil pointer

func (*Array64) Resize

func (a *Array64) Resize(shape ...int) *Array64

Resize will change the underlying array size.

Make a copy C() if the original array needs to remain unchanged. Element location in the underlying slice will not be adjusted to the new shape.

func (*Array64) Set

func (a *Array64) Set(val float64, index ...int) *Array64

Set sets the element at the given index. There should be one index per axis. Generates a ShapeError if incorrect index.

func (*Array64) SetSliceElement

func (a *Array64) SetSliceElement(vals []float64, index ...int) *Array64

SetSliceElement sets the element group at one axis above the leaf elements. Source Array is returned, for function-chaining design.

func (*Array64) SetSubArr

func (a *Array64) SetSubArr(vals *Array64, index ...int) *Array64

SetSubArr sets the array below a given index to the values in vals. Values will be broadcast up multiple axes if the shapes match.

func (*Array64) Shape

func (a *Array64) Shape() []int

Shape returns a copy of the array shape

func (*Array64) SliceElement

func (a *Array64) SliceElement(index ...int) (ret []float64)

SliceElement returns the element group at one axis above the leaf elements. Data is returned as a copy in a float slice.

func (*Array64) String

func (a *Array64) String() (s string)

String Satisfies the Stringer interface for fmt package

func (*Array64) SubArr

func (a *Array64) SubArr(index ...int) (ret *Array64)

SubArr slices the array at a given index.

func (*Array64) Subtr

func (a *Array64) Subtr(b *Array64) *Array64

Subtr performs element-wise subtraction. Arrays must be the same size or albe to broadcast. This will modify the source array.

func (*Array64) SubtrC

func (a *Array64) SubtrC(b float64) *Array64

SubtrC subtracts a constant from all elements of the array.

func (*Array64) Sum

func (a *Array64) Sum(axis ...int) (r *Array64)

Sum calculates the sum result array along a given axes. Empty call gives the grand sum of all elements.

func (*Array64) UnmarshalJSON

func (a *Array64) UnmarshalJSON(b []byte) error

UnmarshalJSON fulfills the json.Unmarshaler interface for decoding data. Custom Unmarshaler is needed to load/decode unexported values and build strides.

type Arrayb

type Arrayb struct {
	// contains filtered or unexported fields
}

Arrayb is an n-dimensional array of boolean values

func Fullb

func Fullb(val bool, shape ...int) (a *Arrayb)

Fullb creates an Arrayb object with dimensions givin in order from outer-most to inner-most All elements will be set to 'val' in the returned array.

func NewArrayB

func NewArrayB(data []bool, shape ...int) (a *Arrayb)

NewArrayB creates an Arrayb object with dimensions given in order from outer-most to inner-most All values will default to false

func (*Arrayb) All

func (a *Arrayb) All(axis ...int) *Arrayb

All will return true if all elements are non-zero, false otherwise.

func (*Arrayb) Any

func (a *Arrayb) Any(axis ...int) *Arrayb

Any will return true if any element is non-zero, false otherwise.

func (*Arrayb) Append

func (a *Arrayb) Append(val *Arrayb, axis int) *Arrayb

Append will concatenate a and val at the given axis.

Source array will be changed, so use C() if the original data is needed. All axes must be the same except the appending axis.

func (*Arrayb) At

func (a *Arrayb) At(index ...int) bool

At returns a copy of the element at the given index. Any errors will return a false value and record the error for the HasErr() and GetErr() functions.

func (*Arrayb) C

func (a *Arrayb) C() (b *Arrayb)

C will return a deep copy of the source array.

func (*Arrayb) Equals

func (a *Arrayb) Equals(b *Arrayb) (r *Arrayb)

Equals performs boolean '==' element-wise comparison

func (*Arrayb) GetDebug

func (a *Arrayb) GetDebug() (err error, debugStr, stackTrace string)

GetDebug returns and clears the error object from the array object. The returned debug string will include the function that generated the error and the arguments that caused it.

This debug information will only be generated and returned if numgo.Debug is set to true before the function call that causes the error.

func (*Arrayb) GetErr

func (a *Arrayb) GetErr() (err error)

GetErr returns the error object and clears the error from the array.

This will only return an error value once per error instance. Do not use it in the if statement to test for the existence of an error. HasErr() is provided for that purpose.

func (*Arrayb) HasErr

func (a *Arrayb) HasErr() bool

HasErr tests for the existence of an error on the Arrayb object.

Errors will be maintained through a chain of function calls, so only the first error will be returned when GetErr() is called. Use HasErr() as a gate for the GetErr() or GetDebug() choice in error handling code.

func (*Arrayb) MarshalJSON

func (a *Arrayb) MarshalJSON() ([]byte, error)

MarshalJSON fulfills the json.Marshaler Interface for encoding data. Custom Unmarshaler is needed to encode/send unexported values.

func (*Arrayb) NotEq

func (a *Arrayb) NotEq(b *Arrayb) (r *Arrayb)

NotEq performs boolean '1=' element-wise comparison

func (*Arrayb) Reshape

func (a *Arrayb) Reshape(shape ...int) *Arrayb

Reshape Changes the size of the array axes. Values are not changed or moved. This must not change the size of the array. Incorrect dimensions will return a nil pointer

func (*Arrayb) Resize

func (a *Arrayb) Resize(shape ...int) *Arrayb

Resize will change the underlying array size.

Make a copy C() if the original array needs to remain unchanged. Element location in the underlying slice will not be adjusted to the new shape.

func (*Arrayb) Set

func (a *Arrayb) Set(val bool, index ...int) *Arrayb

Set sets the element at the given index. There should be one index per axis. Generates a ShapeError if incorrect index.

func (*Arrayb) SetSliceElement

func (a *Arrayb) SetSliceElement(vals []bool, index ...int) *Arrayb

SetSliceElement sets the element group at one axis above the leaf elements. Source Array is returned, for function-chaining design.

func (*Arrayb) SetSubArr

func (a *Arrayb) SetSubArr(vals *Arrayb, index ...int) *Arrayb

SetSubArr sets the array below a given index to the values in vals. Values will be broadcast up multiple axes if the shapes match.

func (*Arrayb) SliceElement

func (a *Arrayb) SliceElement(index ...int) (ret []bool)

SliceElement returns the element group at one axis above the leaf elements. Data is returned as a copy in a float slice.

func (*Arrayb) String

func (a *Arrayb) String() (s string)

String Satisfies the Stringer interface for fmt package

func (*Arrayb) SubArr

func (a *Arrayb) SubArr(index ...int) (ret *Arrayb)

SubArr slices the array object by the index received on each corresponding axis.

These are applied startig from the top axis. Intermediate slicing of axes is not available at this point.

func (*Arrayb) UnmarshalJSON

func (a *Arrayb) UnmarshalJSON(b []byte) error

UnmarshalJSON fulfills the json.Unmarshaler interface for decoding data. Custom Unmarshaler is needed to load/decode unexported values and build strides.

type FoldFunc

type FoldFunc func([]float64) float64

FoldFunc can be received by Fold and FoldCC to apply as a summary function across one or multiple axes.

type MapFunc

type MapFunc func(float64) float64

MapFunc can be received by Map to modify each element in an array.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL