apop_data.c File Reference

Functions

• apop_data * apop_data_alloc (const size_t vsize, const size_t msize1, const int msize2)
• apop_data * apop_data_calloc (const size_t vsize, const size_t msize1, const int msize2)
• apop_data * apop_matrix_to_data (gsl_matrix *m)
• apop_data * apop_vector_to_data (gsl_vector *v)
• void apop_text_free (char ***freeme, int rows, int cols)
• void apop_data_free (apop_data *freeme)
• void apop_data_memcpy (apop_data *out, const apop_data *in)
• apop_data * apop_data_copy (const apop_data *in)
• apop_data * apop_data_stack (apop_data *m1, apop_data *m2, char posn, char inplace)
• apop_data ** apop_data_split (apop_data *in, int splitpoint, char r_or_c)
• void apop_data_rm_columns (apop_data *d, int *drop)
• double * apop_data_ptr (const apop_data *data, const int i, const int j)
• double * apop_data_ptr_ti (const apop_data *in, char *row, int col)
• double * apop_data_ptr_it (const apop_data *in, size_t row, char *col)
• double * apop_data_ptr_tt (const apop_data *in, char *row, char *col)
• double apop_data_get (const apop_data *in, size_t row, int col)
• double apop_data_get_ti (const apop_data *in, char *row, int col)
• double apop_data_get_it (const apop_data *in, size_t row, char *col)
• double apop_data_get_tt (const apop_data *in, char *row, char *col)
• void apop_data_set (apop_data *in, size_t row, int col, double data)
• void apop_data_set_ti (apop_data *in, char *row, int col, double data)
• void apop_data_set_it (apop_data *in, size_t row, char *col, double data)
• void apop_data_set_tt (apop_data *in, char *row, char *col, double data)
• void apop_data_add_named_elmt (apop_data *d, char *name, double val)
• void apop_text_add (apop_data *in, const size_t row, const size_t col, const char *fmt,...)
• apop_data * apop_text_alloc (apop_data *in, const size_t row, const size_t col)
• apop_data * apop_data_transpose (apop_data *in)
• gsl_matrix * apop_matrix_realloc (gsl_matrix *m, size_t newheight, size_t newwidth)
• gsl_vector * apop_vector_realloc (gsl_vector *v, size_t newheight)

---

Detailed Description

The apop_data structure joins together a gsl_matrix, apop_name, and a table of strings.

---

Function Documentation

void apop_data_add_named_elmt	(	apop_data *	d,
		char *	name,
		double	val
	)

A convenience function to add a named element to a data vector. For example, many of the testing procedures use this to easily produce a column of named parameters.

Parameters:

	d	The apop_data structure. Must not be NULL.
	name	The name to add
	val	the value to add to the vector.

• I use the position of the name to know where to put the value. If there are two names in the data set, then I will put the new name in the third name slot and the data in the third slot in the vector. If you use this function from start to finish in building your vector, then you'll be fine.

• If the vector is too short (or NULL), I will call apop_vector_realloc internally to make space in the vector.

apop_data** apop_data_split	(	apop_data *	in,
		int	splitpoint,
		char	r_or_c
	)

Split one input apop_data structure into two.

For the opposite operation, see apop_data_stack.

The apop_data->vector is taken to be the -1st element of the matrix.

Parameters:

	in	The apop_data structure to split
	splitpoint	The index of what will be the first row/column of the second data set. E.g., if this is -1 and r_or_c=='c', then the whole data set will be in the second data set; if this is the length of the matrix then the whole data set will be in the first data set. Another way to put it is that splitpoint will equal the number of rows/columns in the first matrix (unless it is -1, in which case the first matrix will have zero rows, or it is greater than the matrix's size, in which case it will have as many rows as the original).
	r_or_c	If this is 'r' or 'R', then cleave the rows; of 'c' or 'C' cleave the columns.

Returns:

An array of two apop_data sets. If one is empty then a NULL pointer will be returned in that position. For example, for a data set of 50 rows, apop_data **out = apop_data_split(data, 100, 'r') sets out[0] = apop_data_copy(data) and out[1] = NULL.

• Weights will be preserved. If splitting by rows, then the top and bottom parts of the weights vector will be assigned to the top and bottom parts of the main data set. If splitting by columns, identical copies of the weights vector will be assigned to both parts.

apop_data* apop_data_transpose

(

apop_data *

in

)

Transpose the matrix element of the input apop_data set, including the row/column names. The vector and text elements of the input data set are completely ignored.

This is really just a friendly wrapper for gsl_matrix_transpose_memcpy; if you have a gsl_matrix with no names, you may prefer to just use that function.

Parameters:

in

The input apop_data set.

Returns:

A newly alloced apop_data set, with the appropriately transposed matrix. The vector and text elements will be NULL.

gsl_matrix* apop_matrix_realloc	(	gsl_matrix *	m,
		size_t	newheight,
		size_t	newwidth
	)

This function will resize a gsl_matrix to a new height or width.

Data in the matrix will be retained. If the new height or width is smaller than the old, then data in the later rows/columns will be cropped away (in a non--memory-leaking manner). If the new height or width is larger than the old, then new cells will be filled with garbage; it is your repsonsibility to zero out or otherwise fill new rows/columns before use.

Warning I: Using this function is basically bad form---especially when used in a for loop that adds a column each time. A large number of reallocs can take a noticeable amount of time. You are thus encouraged to make an effort to determine the size of your data beforehand.

Warning II: The gsl_matrix is a versatile struct that can represent submatrices and other cuts from parent data. I can't deal with those, and check for such situations beforehand. [Besides, resizing a portion of a parent matrix makes no sense.]

Parameters:

	m	The already-allocated matrix to resize. If you give me NULL, this becomes equivalent to gsl_matrix_alloc
	newheight,newwidth	The height and width you'd like the matrix to be.

Returns:

m, now resized

apop_data* apop_matrix_to_data

(

gsl_matrix *

m

)

Wrap an apop_data structure around an existing gsl_matrix. The matrix is not copied, but is pointed to by the new apop_data struct.

Parameters:

m

The existing matrix you'd like to turn into an apop_data structure.

Returns:

The apop_data structure whose matrix pointer points to the input matrix. The rest of the struct is basically blank.

void apop_text_add	(	apop_data *	in,
		const size_t	row,
		const size_t	col,
		const char *	fmt,
			...
	)

Add a string to the text element of an apop_data set. If you send me a NULL string, I will write the string "NaN" in the given slot.

Parameters:

	in	The apop_data set, that already has an allocated text element.
	row	The row
	col	The col
	fmt	The text to write.
	...	You can use a printf-style fmt and follow it with the usual variables to fill in.

apop_data* apop_text_alloc	(	apop_data *	in,
		const size_t	row,
		const size_t	col
	)

This allocates an array of strings and puts it in the text element of an apop_data set.

Parameters:

	in	An apop_data set. It's OK to send in NULL, in which case an apop_data set with NULL matrix and vector elements is returned.
	row	the number of rows of text.
	col	the number of columns of text.

Returns:

A pointer to the relevant apop_data set. If the input was not NULL, then this is a repeat of the input pointer.

void apop_text_free	(	char ***	freeme,
		int	rows,
		int	cols
	)

Free a matrix of chars* (i.e., a char***). This is the form of the text element of the apop_data set, so you can use this for:

 apop_text_free(yourdata->text, yourdata->textsize[0], yourdata->textsize[1]);

This is what apop_data_free uses internally.

gsl_vector* apop_vector_realloc	(	gsl_vector *	v,
		size_t	newheight
	)

This function will resize a gsl_vector to a new length.

Data in the vector will be retained. If the new height is smaller than the old, then data in the bottom of the vector will be cropped away (in a non--memory-leaking manner). If the new height is larger than the old, then new cells will be filled with garbage; it is your repsonsibility to zero out or otherwise fill them before use.

Warning I: Using this function is basically bad form---especially when used in a for loop that adds an element each time. A large number of reallocs can take a noticeable amount of time. You are thus encouraged to make an effort to determine the size of your data beforehand.

Warning II: The gsl_vector is a versatile struct that can represent subvectors, matrix columns and other cuts from parent data. I can't deal with those, and check for such situations beforehand. [Besides, resizing a portion of a parent matrix makes no sense.]

Parameters:

	v	The already-allocated vector to resize. If you give me NULL, this is equivalent to gsl_vector_alloc
	newheight	The height you'd like the vector to be.

Returns:

v, now resized

apop_data* apop_vector_to_data

(

gsl_vector *

v

)

Wrap an apop_data structure around an existing gsl_vector. The vector is not copied, but is pointed to by the new apop_data struct.

Parameters:

v

The data vector

Returns:

an allocated, ready-to-use apop_data struture.