Variable

group harp_variable

The HARP Variables module contains everything related to HARP variables.

Typedefs

typedef struct harp_variable_struct harp_variable

HARP Variable typedef

Functions

int harp_variable_convert_unit(harp_variable *variable, const char *target_unit)

Perform unit conversion on a variable

Apply an automatic conversion on the variable to arrive at the new given unit. If there is no conversion available from the current unit to the new unit then an error will be raised. The data type of the variable will be changed to ‘double’ as part of the conversion.

Parameters:

  • variable – Variable on which the apply unit conversion.

  • target_unit – Unit to which the variable should be converted (use udunits2 compliant units).

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_new(const char *name, harp_data_type data_type, int num_dimensions, const harp_dimension_type *dimension_type, const long *dimension, harp_variable **new_variable)

Create new variable.

Parameters:

  • name – Name of the variable.

  • data_type – Storage type of the variable data.

  • num_dimensions – Number of array dimensions (use ‘0’ for scalar data).

  • dimension_type – Array with the dimension type for each of the dimensions.

  • dimension – Array with length for each of the dimensions.

  • new_variable – Pointer to the C variable where the new HARP variable will be stored.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

void harp_variable_delete(harp_variable *variable)

Delete variable. Remove variable and all attached attributes.

Parameters:

variable – HARP variable

int harp_variable_copy(const harp_variable *other_variable, harp_variable **new_variable)

Create a copy of a variable. The function will create a deep-copy of the given HARP variable, also creating copyies of all attributes.

Parameters:

  • other_variable – Variable that should be copied.

  • new_variable – Pointer to the C variable where the new HARP variable will be stored.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_copy_attributes(const harp_variable *variable, harp_variable *target_variable)

Copy all attributes of a variable to a target variable. This will copy all attribute information of a variable that is not available as a parameter of harp_variable_new.

Parameters:

  • variable – Variable from which the attributes should be copied.

  • target_variable – Variable into which the attributes will be stored.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_append(harp_variable *variable, const harp_variable *other_variable)

Append one variable to another. Both variables need to have the ‘time’ dimension as first dimension. And all non-time dimensions need to be the same for both variables.

Parameters:

  • variable – Variable to which data should be appended.

  • other_variable – Variable that should be appended.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_rename(harp_variable *variable, const char *name)

Change the name of a variable.

Parameters:

  • variable – The variable for which the name should be changed.

  • name – The new name of the variable.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_set_unit(harp_variable *variable, const char *unit)

Set the unit attribute of the specified variable. Store a copy of unit as the value of the unit attribute of the specified variable. The previous value (if any) will be freed.

Parameters:

  • variable – Variable for which to set the unit attribute.

  • unit – New value for the unit attribute.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_set_description(harp_variable *variable, const char *description)

Set the description attribute of the specified variable. Store a copy of description as the value of the description attribute of the specified variable. The previous value (if any) will be freed.

Parameters:

  • variable – Variable for which to set the description attribute.

  • description – New value for the description attribute.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_set_enumeration_values(harp_variable *variable, int num_enum_values, const char **enum_name)

Set the enumeration values for a variable with integer values. This will assign enumeration labels to each integer value from 0 to num_enum_values-1. The enumeration label for a value is found by using the value as index in the enum_name array. This function will also set valid_min to 0 and valid_max to num_enum_values - 1 (i.e. any variable value that lies outside the index range is considered invalid). You can pass num_enum_values = 0 to clear any previous enumeration values that were set for the variable.

Parameters:

  • variable – Variable for which to set the enumeration values.

  • num_enum_values – Number of enumeration values

  • enum_name – Array with the names for each of the enumeration values

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_set_string_data_element(harp_variable *variable, long index, const char *str)

Store a copy of str at index into the flattened array of strings associated with variable.

Warning

No boundary checks are performed on index.

Parameters:

  • variable – Variable of type string.

  • index – Index into the flattened array of strings associated with the variable.

  • str – The string of which a copy should be stored.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_convert_data_type(harp_variable *variable, harp_data_type target_data_type)

Convert the data for the variable such that it matches the given data type. The memory for the block holding the data for the attribute will be resized to match the new data type if needed. You cannot convert string data to numeric data or vice-versa. Conversion from floating point to integer data (or vice versa) is allowed though.

Parameters:

  • variable – Variable whose data should be aligned with the given data type.

  • target_data_type – Data type to which the data for the variable should be converted.

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

int harp_variable_has_dimension_type(const harp_variable *variable, harp_dimension_type dimension_type)

Test if variable contains at least one dimension equal to the specified dimension type.

Parameters:

  • variable – Variable to check.

  • dimension_type – Requested dimension type

Returns:

  • 0, Variable does not contain a dimension of the given dimension type

  • 1, Variable contains at least one dimension of the given dimension type

int harp_variable_has_dimension_types(const harp_variable *variable, int num_dimensions, const harp_dimension_type *dimension_type)

Test if variable has dimensions equal to the specified list of dimension types.

Parameters:

  • variable – Variable to check.

  • num_dimensions – Number of dimensions the variable should have.

  • dimension_type – Requested dimension type for each of the dimensions of the variable

Returns:

  • 0, Variable does not match the dimension types

  • 1, Variable matches number of dimensions and specified type for each dimension.

int harp_variable_has_unit(const harp_variable *variable, const char *unit)

Test if variable has a unit equal to the specified unit.

Parameters:

  • variable – Variable to check.

  • unit – Number of dimensions the variable should have.

Returns:

  • 0, The unit of the variable does not equal the given unit

  • 1, The unit of the variable equals the given unit

int harp_variable_verify(const harp_variable *variable)

Verify that a variable is internally consistent and complies with conventions.

Parameters:

variable – Variable to verify.

Returns:

  • 0, Variable verified successfully.

  • -1, Error occurred (check harp_errno).

void harp_variable_print(harp_variable *variable, int show_attributes, int (*print)(const char*, ...))

Print a harp_variable struct using the specified print function.

Parameters:

  • variable – Variable to print.

  • show_attributes – Whether or not to print the attributes.

  • print – Print function to use

void harp_variable_print_data(harp_variable *variable, int (*print)(const char*, ...))

Print the data of a harp_variable using the specified print function.

Parameters:

  • variable – Variable whose data to print.

  • print – Print function to use

int harp_variable_smooth_vertical(harp_variable *variable, harp_variable *vertical_axis, harp_variable *averaging_kernel, harp_variable *apriori)

Vertically smooth the variable using the given averaging kernel and a apriori. The variable already needs to be on the same vertical grid as that of the averaging kernel (and a priori). The apriori is optional. If provided, the apriori is first subtracted from the variable, then the smoothing is performed, and finally the apriori is added again. The averaging kernel needs to have dimensions {time,vertical,vertical} and the apriori {time,vertical}. The variable to be smoothed needs to have dimensions {time, …, vertical} (i.e. first dimension must be time and the last the vertical dimension; number of dimensions needs to be 2 or higher). The vertical axis variable is optional and, if provided, needs to have dimensions {time,vertical}. The vertical axis variable will be used to determine the valid number of vertical elements per profile. All inputs need to be provided as ‘double’ data.

Parameters:

  • variable – Variable to which the averaging kernel (and apriori) should be applied.

  • vertical_axis – The variable containing the time dependent vertical grid (optional).

  • averaging_kernel – The variable containing the averaging kernel.

  • apriori – The variable containing the apriori (optional).

Returns:

  • 0, Success.

  • -1, Error occurred (check harp_errno).

struct harp_variable_struct
#include <harp.h>

HARP Variable struct

Public Members

char *name

name of variable

harp_data_type data_type

storage type of the data

int num_dimensions

number of array dimensions

harp_dimension_type dimension_type[HARP_MAX_NUM_DIMS]

type of each of the array dimensions

long dimension[HARP_MAX_NUM_DIMS]

length of each of the array dimensions

long num_elements

total number of elements (equals product of array dimensions)

harp_array data

array data of the variable

char *description

corresponds to netCDF long_name

char *unit

corresponds to netCDF units

harp_scalar valid_min

corresponds to netCDF valid_min or valid_range[0]

harp_scalar valid_max

corresponds to netCDF valid_max or valid_range[1]

int num_enum_values

number of enumeration values (which map to values 0..N-1 in ‘data’)

char **enum_name

name of each enumeration value