Things to make life easier with the GSL

Defines

#define apop_sum(in) apop_vector_sum(in)

Functions

char * apop_strip_dots (char *in, char strip_type)
gsl_rng * apop_rng_alloc (int seed)
gsl_matrix * apop_vector_to_matrix (const gsl_vector *in, char row_col)
gsl_vector * apop_vector_copy (const gsl_vector *in)
gsl_matrix * apop_matrix_copy (const gsl_matrix *in)
void apop_vector_increment (gsl_vector *v, int i, double amt)
void apop_matrix_increment (gsl_matrix *m, int i, int j, double amt)
void apop_vector_log10 (gsl_vector *v)
void apop_vector_log (gsl_vector *v)
void apop_vector_exp (gsl_vector *v)
gsl_vector * apop_vector_stack (gsl_vector *v1, gsl_vector *v2, char inplace)
gsl_matrix * apop_matrix_stack (gsl_matrix *m1, gsl_matrix *m2, char posn, char inplace)
int apop_vector_bounded (const gsl_vector *in, long double max)
long double apop_vector_sum (const gsl_vector *in)
double apop_vector_distance (const gsl_vector *ina, const gsl_vector *inb, const char metric, const double norm)
double apop_vector_grid_distance (const gsl_vector *ina, const gsl_vector *inb)
long double apop_matrix_sum (const gsl_matrix *m)
double apop_matrix_mean (const gsl_matrix *data)
double apop_matrix_var_m (const gsl_matrix *data, double mean)
void apop_matrix_mean_and_var (const gsl_matrix *data, double *mean, double *var)

Define Documentation

#define apop_sum ( in ) apop_vector_sum(in)

An alias for apop_vector_sum. Returns the sum of the data in the given vector.

Function Documentation

gsl_matrix * apop_matrix_copy ( const gsl_matrix * in )

Copy one gsl_matrix to another. That is, all data is duplicated. Unlike gsl_matrix_memcpy, this function allocates and returns the destination, so you can use it like this:

 gsl_matrix *a_copy = apop_matrix_copy(original);

Parameters:

in

the input data

Returns:: a structure that this function will allocate and fill

void apop_matrix_increment	(	gsl_matrix *	m,
		int	i,
		int	j,
		double	amt
	)

Just add amt to a gsl_matrix element. This is a readable convenience function that does some checks along the way. If you need speed, try, e.g.,

  *gsl_matrix_ptr(v, i, j) += amt;

which is roughly 25% faster by my tests.

Parameters:

	m	The `gsl_matrix` in question (No default, must not be `NULL`)
	i	The row of the element to be incremented. (No default)
	j	The column of the element to be incremented. (No default)
	amt	The amount by which to increment. Of course, one can decrement by specifying a negative amount. (default = 1. Please note that it is impossible to increment by zero. If that glitch is a possibility, use `apop_vector_increment_base`.)

double apop_matrix_mean ( const gsl_matrix * data )

Returns the mean of all elements of a matrix.

Calculated to avoid overflow errors.

Parameters:

data

the matrix to be averaged.

void apop_matrix_mean_and_var	(	const gsl_matrix *	data,
		double *	mean,
		double *	var
	)

Returns the mean and variance of all elements of a matrix.

Parameters:

	data	the matrix to be averaged.
	mean	where to put the mean to be calculated
	var	where to put the variance to be calculated

gsl_matrix* apop_matrix_stack	(	gsl_matrix *	m1,
		gsl_matrix *	m2,
		char	posn,
		char	inplace
	)

Put the first matrix either on top of or to the right of the second matrix. The fn returns a new matrix, meaning that at the end of this function, until you gsl_matrix_free() the original matrices, you will be taking up twice as much memory. Plan accordingly.

Parameters:

	m1	the upper/rightmost matrix (default=`NULL`, in which case this basically copies `m2`)
	m2	the second matrix (default = `NULL`, in which case `m1` is returned)
	posn	if 'r', stack rows on top of other rows, else, e.g. 'c' stack columns next to columns. (default ='r')
	inplace	If one, use apop_matrix_realloc to modify `m1` in place; see the caveats on that function. Otherwise, allocate a new matrix, leaving `m1` unmolested. (default=0)

Returns:: the stacked data, either in a new matrix or a pointer to m1.

For example, here is a little function to merge four matrices into a single two-part-by-two-part matrix. The original matrices are unchanged.

gsl_matrix *apop_stack_two_by_two(gsl_matrix *ul, gsl_matrix *ur, gsl_matrix *dl, gsl_matrix *dr){
  gsl_matrix *output, *t;
    output = apop_matrix_stack(ul, ur, 'c');
    t = apop_matrix_stack(dl, dr, 'c');
    apop_matrix_stack(output, t, 'r', .inplace=1);
    gsl_matrix_free(t);
    return output;
}

This function uses the Designated initializers syntax for inputs.

long double apop_matrix_sum ( const gsl_matrix * m )

Returns the sum of the elements of a matrix. Occasionally convenient.

Parameters:

m

the matrix to be summed.

double apop_matrix_var_m	(	const gsl_matrix *	data,
		double	mean
	)

Returns the variance of all elements of a matrix, given the mean. If you want to calculate both the mean and the variance, use apop_matrix_mean_and_var.

Parameters:

	data	the matrix to be averaged.
	mean	the pre-calculated mean

gsl_rng* apop_rng_alloc ( int seed )

Initialize a gsl_rng.

Uses the Tausworth routine.

Parameters:

seed

The seed. No need to get funny with it: 0, 1, and 2 will produce wholly different streams.

Returns:: The RNG ready for your use.

char* apop_strip_dots	(	char *	in,
		char	strip_type
	)

Strip dots from a name.

Parameters:

	in	A string
	strip_type	'd': replace all '.' with '_'. 'b': return only the string before the '.', so 'table.col' becomes 'table'. If there are multiple dots, cuts off at the first dot. 'a': return only the string after the '.', so 'table.col' becomes 'col'. If there are multiple dots, cuts off at the last dot.

int apop_vector_bounded	(	const gsl_vector *	in,
		long double	max
	)

Test for a situation when a vector is diverging, so you can preempt a procedure that is about to break on infinite values.

Alternatively, set max to INFINITY (or GSL_INF) to just test whether all of the matrix's elements are finite.

Parameters:

	in	A `gsl_vector`
	max	An upper and lower bound to the elements of the vector. (default: GSL_POSINF)

Returns:: 1 if everything is bounded: not Inf, -Inf, or NaN, and $-\max < x < \max$ ; zero otherwise. A NULL vector has no unbounded elements, so NULL input returns 1.

This function uses the Designated initializers syntax for inputs.

gsl_vector * apop_vector_copy ( const gsl_vector * in )

Copy one gsl_vector to another. That is, all data is duplicated. Unlike gsl_vector_memcpy, this function allocates and returns the destination, so you can use it like this:

 gsl_vector *a_copy = apop_vector_copy(original);

Parameters:

in

the input data

Returns:: a structure that this function will allocate and fill

double apop_vector_distance	(	const gsl_vector *	ina,
		const gsl_vector *	inb,
		const char	metric,
		const double	norm
	)

Returns the distance between two vectors, where distance is defined based on the third (optional) parameter:

'e' or 'E' (the default): scalar distance (standard Euclidian metric) between two vectors. Simply $\sqrt{\sum_i{(a_i - b_i)^2}},$ where iterates over dimensions.

'm' or 'M' Returns the Manhattan metric distance between two vectors: $\sum_i{|a_i - b_i|},$ where iterates over dimensions.

'd' or 'D' The discrete norm: if , return zero, else return one.

's' or 'S' The sup norm: find the dimension where is largest, return the distance along that one dimension.
'l' or 'L' The norm, $\left(\sum_i{(a_i - b_i)^2}\right)^{1/p},$ . The value of is set by the fourth (optional) argument.

Parameters:

	ina	First vector (No default, must not be `NULL`)
	inb	Second vector (Default = zero)
	metric	The type of metric, as above.
	norm	If you are using an norm, this is . Must be strictly greater than zero. (default = 2)

Notice that the defaults are such that

 apop_vector_distance(v);
 apop_vector_distance(v, .metric = 's');

gives you the standard Euclidian length of v and its longest element.

This function uses the Designated initializers syntax for inputs.

void apop_vector_exp ( gsl_vector * v )

Replace every vector element $v_i$ with exp( $v_i$ ).

double apop_vector_grid_distance	(	const gsl_vector *	ina,
		const gsl_vector *	inb
	)

Returns the scalar Manhattan metric distance between two vectors. Simply $\sum_i{|a_i - b_i|},$ where $i$ iterates over dimensions.

Equivalent to apop_vector_distance(ina, inb, .metric='M').

void apop_vector_increment	(	gsl_vector *	v,
		int	i,
		double	amt
	)

Just add amt to a gsl_vector element. This is a readable convenience function that does some checks along the way. If you need speed, try, e.g.,

  *gsl_vector_ptr(v, i) += amt;

which is roughly 25% faster by my tests.

Parameters:

	v	The `gsl_vector` in question (No default, must not be NULL)
	i	The location in the vector to be incremented. (No default)
	amt	The amount by which to increment. Of course, one can decrement by specifying a negative amount. (default = 1. Please note that it is impossible to increment by zero. If that glitch is a possibility, use `apop_vector_increment_base`.)

This function uses the Designated initializers syntax for inputs.

void apop_vector_log ( gsl_vector * v )

Take the natural log of every element in a vector.

void apop_vector_log10 ( gsl_vector * v )

Take the log (base ten) of every element in a vector.

gsl_vector* apop_vector_stack	(	gsl_vector *	v1,
		gsl_vector *	v2,
		char	inplace
	)

Put the first vector on top of the second vector.

Parameters:

	v1	the upper vector (default=`NULL`, in which case this basically copies `v2`)
	v2	the second vector (default=`NULL`, in which case nothing is added)
	inplace	If one, use apop_vector_realloc to modify `v1` in place; see the caveats on that function. Otherwise, allocate a new vector, leaving `v1` unmolested. (default=0)

Returns:: the stacked data, either in a new vector or a pointer to v1.

This function uses the Designated initializers syntax for inputs.

long double apop_vector_sum ( const gsl_vector * in )

Returns the sum of the data in the given vector.

gsl_matrix * apop_vector_to_matrix	(	const gsl_vector *	in,
		char	row_col
	)

Mathematically, a vector of size $N$ and a matrix of size $N \times 1$ are equivalent, but they're two different types in C. This function copies the data in a vector to a new one-column (or one-row) matrix and returns the newly-allocated and filled matrix.

For the reverse, try apop_data_pack.

Parameters:

	in	a `gsl_vector` (No default. If `NULL`, I return `NULL`, with a warning if `apop_opts.verbose >=1` )
	row_col	If `'r'`, then this will be a row (1 x N) instead of the default, a column (N x 1). (default: `'c'`)

Returns:: a newly-allocated gsl_matrix with one column.

This function uses the Designated initializers syntax for inputs.

Apophenia

Things to make life easier with the GSL

Defines

Functions

Define Documentation

Function Documentation