Product — HARP 1.15 documentation

# Product

group `harp_product`

  The HARP Products module contains everything related to HARP products.

  The representation of a HARP product in C is a structure containing:

  - an array of variables

  - an array of dimension lengths for each dimension type (unavailable dimensions have length -1)

  - the `source_product` global attribute (can be NULL)

  - the `history` global attribute (can be NULL)

  Note that the `Conventions` global attribute is not included as this is automatically handled by the import/export functions of HARP. Similar, the `datetime_start` and `datetime_stop` attributes are handled by the export function. They are set to the minimum and maximum values of the variables `datetime`, `datetime_start` and `datetime_stop` (if available).

  For each variable in the HARP product the dimensions need to match the length of their type as defined in the dimension array of the HARP product (for all dimension types except ‘independent’).

  Typedefs

  typedef struct harp_product_struct `harp_product`

    HARP Product typedef

  Functions

  int `harp_product_bin`(harp_product *product, long num_bins, long num_elements, long *bin_index)

    Bin the product’s variables. This will bin all variables in the time dimension. Each time sample will be put in the bin defined by bin_index. All variables with a time dimension will then be resampled using these bins. The resulting value for each variable will be the average of all values for the bin (using existing count or weight variables as weighting factors where available). Variables with multiple dimensions will have all elements in the sub dimensions averaged on an element by element basis.

    Variables that have a time dimension but no unit (or using a string data type) will be removed. The exception are count and weight variables, which will be summed.

    All variables that are binned (except existing count/weight variables) are converted to a double data type. Bins that have no samples will end up with a NaN value.

    If the product did not already have a ‘count’ variable then a ‘count’ variable will be added to the product that will contain the number of samples per bin.

    Only non-NaN values will contribute to a bin. If there are NaN values and there is not already a variable-specific count or weight variable for that variable, then a separate variable-specific count variable will be created that will contain the number of non-NaN values that contributed to each bin. This count variable will have the same dimensions as the variable it provides the count for.

    For angle variables a variable-specific weight variable will be created (if it did not yet exist) that contains the magnitude of the sum of the unit vectors that was used to calculate the angle average.

    For uncertainty variables the first order propagation rules are used (assuming full correlation for systematic uncertainty variables and using the harp_get_option_propagate_uncertainty() setting for total and random uncertainty variables).

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to regrid.

      - `num_bins`: Number of target bins.

      - `num_elements`: Length of bin_index array (should equal the length of the time dimension)

      - `bin_index`: Array of target bin index numbers (0 .. num_bins-1) for each sample in the time dimension.

  int `harp_product_bin_spatial`(harp_product *product, long num_time_bins, long num_time_elements, long *time_bin_index, long num_latitude_edges, double *latitude_edges, long num_longitude_edges, double *longitude_edges)

    Bin the product’s variables into a spatial grid. This will bin all variables with a time dimension into a three dimensional time x latitude x longitude grid. Each time sample will first be allocated to a time bin defined by time_bin_index (similar to harp_product_bin). Then within that time bin the sample will be allocated to the appropriate cell(s) in the latitude/longitude grid as defined by the latitude_edges and longitude_edges variables.

    The lat/lon grid will be a fixed time-independent grid and will have ‘num_latitude_edges-1’ latitudes and ‘num_longitude_edges-1’ longitudes. The latitude_edges and longitude_edges arrays provide the boundaries of the grid cells in degrees and need to be provided in a strict ascending order. The latitude edge values need to be between -90 and 90 and for the longitude edge values the constraint is that the difference between the last and first edge should be <= 360.

    If the product has latitude_bounds {time,independent} and longitude_bounds {time,independent} variables then an area binning is performed. This means that each sample will be allocated to each lat/lon grid cell based on the amount of overlap. This overlap calculation will treat lines between points as straight lines within the carthesian plane (i.e. using a Plate Carree projection, and not using great circle arcs between points on a sphere).

    If the product doesn’t have lat/lon bounds per sample, it should have latitude {time} and longitude {time} variables. The binning onto the lat/lon grid will then be a point binning. This means that each sample is allocated to only one grid cell based on its lat/lon coordinate. To achieve a unique assignment, for each cell the lower edge will be considered inclusive and the upper edge exclusive (except for the last cell (when there is no wrap-around)).

    The resulting value for each time/lat/lon cell will be the average of all values for that cell. This will be a weighted average in case an area binning is performed and a straight average for point binning. Variables with multiple dimensions will have all elements in its sub dimensions averaged on an element by element basis (i.e. sub dimensions will be retained).

    Variables that have a time dimension but no unit (or using a string data type) will be removed. Any existing count or weight variables will also be removed.

    For uncertainty variables the first order propagation rules are used (assuming full correlation).

    All variables that are binned are converted to a double data type. Cells that have no samples will end up with a NaN value.

    A ‘count’ variable will be added to the product that will contain the number of samples per time bin. In addition, a ‘weight’ variable will be added that will contain the sum of weights for the contribution to each cell. If a variable contained NaN values then a variable specific weight variable will be created with only the sum of weights for the non-NaN entries.

    For angle variables a variable-specific weight variable will be created that contains the magnitude of the sum of the unit vectors that was used to calculate the angle average.

    Axis variables for the time dimension such as datetime, datetime_length, datetime_start, and datetime_stop will only be binned in the time dimension (and will not gain a latitude or longitude dimension).

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to regrid.

      - `num_time_bins`: Number of target bins in the time dimension.

      - `num_time_elements`: Length of bin_index array (should equal the length of the time dimension)

      - `time_bin_index`: Array of target time bin index numbers (0 .. num_bins-1) for each sample in the time dimension.

      - `num_latitude_edges`: Number of edges for the latitude grid (number of latitude rows = num_latitude_edges - 1)

      - `latitude_edges`: latitude grid edge vales

      - `num_longitude_edges`: Number of edges for the longitude grid (number of longitude columns = num_longitude_edges - 1)

      - `longitude_edges`: longitude grid edge vales

  int `harp_product_get_derived_variable`(const harp_product *product, const char *name, const harp_data_type *data_type, const char *unit, int num_dimensions, const harp_dimension_type *dimension_type, harp_variable **variable)

    Retrieve a new variable based on the set of automatic conversions that are supported by HARP.

    If the product already contained a variable with the given name, you will get a copy of that variable (and converted to the specified data type and unit). Otherwise the function will try to create a new variable based on the data found in the product or on available auxiliary data (e.g. built-in climatology). The caller of this function will be responsible for the memory management of the returned variable.

    Note

      setting unit to NULL returns a variable in the original unit

    Note

      pointers to axis variables are passed through unmodified.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product from which to derive the new variable.

      - `name`: Name of the variable that should be created.

      - `data_type`: Data type (optional) of the variable that should be created.

      - `unit`: Unit (optional) of the variable that should be created.

      - `num_dimensions`: Number of dimensions of the variable that should be created.

      - `dimension_type`: Type of dimension for each of the dimensions of the variable that should be created.

      - `variable`: Pointer to the C variable where the derived HARP variable will be stored.

  int `harp_product_add_derived_variable`(harp_product *product, const char *name, const harp_data_type *data_type, const char *unit, int num_dimensions, const harp_dimension_type *dimension_type)

    Create a derived variable and add it to the product.

    If a similar named variable with the right dimensions was already in the product then that variable will be modified to match the given unit (and in case unit is NULL, then the function will just leave the product unmodified). Otherwise the function will call harp_product_get_derived_variable() and add the new variable using harp_product_add_variable() (removing any existing variable with the same name, but different dimensions)

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product from which to derive the new variable and into which the derived variable should be placed.

      - `name`: Name of the variable that should be added.

      - `data_type`: Data type (optional) of the variable that should be added.

      - `unit`: Unit (optional) of the variable that should be added.

      - `num_dimensions`: Number of dimensions of the variable that should be created.

      - `dimension_type`: Type of dimension for each of the dimensions of the variable that should be created.

  int `harp_product_new`(harp_product **new_product)

    Create new product. The product will be initialized with 0 variables and 0 attributes.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `new_product`: Pointer to the C variable where the new HARP product will be stored.

  void `harp_product_delete`(harp_product *product)

    Delete product. Remove product and all attached variables and attributes.

    Parameters

      - `product`: HARP product.

  int `harp_product_copy`(const harp_product *other_product, harp_product **new_product)

    Create a copy of a product. The function will create a deep-copy of the given product, also creating copyies of all attributes and variables.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `other_product`: Product that should be copied.

      - `new_product`: Pointer to the variable where the new HARP product will be stored.

  int `harp_product_append`(harp_product *product, harp_product *other_product)

    Append one product to another. The ‘index’ variable, if present, will be removed. All variables in both products will have a ‘time’ dimension introduced as first dimension. Both products will have all non-time dimensions extended to the maximum of either product. Any ‘source_product’ attribute for the first product will be removed.

    If you pass NULL for ‘other_product’, then ‘product’ will be updated as if it was the result of a merge (i.e. remove ‘index’, add ‘time’ dimension, and remove ‘source_product’ attribute).

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to which data should be appended.

      - `other_product`: (optional) Product that should be appended.

  int `harp_product_set_source_product`(harp_product *product, const char *product_path)

    Set the source product attribute of the specified product. Stores the base name of product_path as the value of the source product attribute of the specified product. The previous value (if any) will be freed. The base name of the product path is the filename of the product without any directory name components.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product for which to set the source product attribute.

      - `product_path`: Relative or absolute path to the product or just the product filename (can be NULL).

  int `harp_product_set_history`(harp_product *product, const char *history)

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

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product for which to set the history attribute.

      - `history`: New value for the history attribute (can be NULL).

  int `harp_product_add_variable`(harp_product *product, harp_variable *variable)

    Add a variable to a product.

    Note

      The memory management of the variable will be handled via the product after you have added the variable.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to which the variable should be added.

      - `variable`: Variable that should be added to the product.

  int `harp_product_detach_variable`(harp_product *product, const harp_variable *variable)

    Detach a variable from a product. Removes a variable from a product without deleting the variable itself. After detaching, the caller of the function will be responsible for the further memory management of the variable.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product from which the variable should be detached.

      - `variable`: Variable that should be detached.

  int `harp_product_remove_variable`(harp_product *product, harp_variable *variable)

    Remove a variable from a product. This function removes the specified variable from the product and then deletes the variable itself.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product from which the variable should be removed.

      - `variable`: Variable that should be removed.

  int `harp_product_remove_variable_by_name`(harp_product *product, const char *name)

    Remove a variable from a product using the name of the variable. This function removes the variable with the specified name from the product and then deletes the variable itself.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product from which the variable should be removed.

      - `name`: Name of the variable that should be removed.

  int `harp_product_replace_variable`(harp_product *product, harp_variable *variable)

    Replaces an existing variable with the one provided. The product should already contain a variable with the same name as variable. This function searches in the list of variables in the product for one with the same name, removes this variable and then adds the given variable in its place. Note that if you try to replace a variable with itself the function does nothing (and returns success).

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product in which the variable should be replaced.

      - `variable`: Variable that should be used to replace an existing variable.

  int `harp_product_has_variable`(const harp_product *product, const char *name)

    Test if product contains a variable with the specified name.

    Return

      - `0`, Product does not contain a variable of the specified name.

      - `1`, Product contains a variable of the specified name.

    Parameters

      - `product`: Product to search.

      - `name`: Name of the variable to search for.

  int `harp_product_get_variable_by_name`(const harp_product *product, const char *name, harp_variable **variable)

    Find variable with a given name for a product. If no variable with the given name can be found an error is returned.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product in which to find the variable.

      - `name`: Name of the variable.

      - `variable`: Pointer to the C variable where the found HARP variable will be stored.

  int `harp_product_get_variable_index_by_name`(const harp_product *product, const char *name, int *index)

    Find index of variable with a given name for a product. If no variable with the given name can be found an error is returned.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product in which the find the variable.

      - `name`: Name of the variable.

      - `index`: Pointer to the C variable where the index in the HARP variables list for the product is returned.

  int `harp_product_is_empty`(const harp_product *product)

    Determine whether all variables in a product have at least one element. If at least one variable has 0 elements or if the product has 0 variables the function returns 1, and 0 otherwise.

    Return

      - `0`, The product does not contain empty data.

      - `1`, The product contains 0 variables or at least one variable has 0 elements.

    Parameters

      - `product`: Product to check for empty data.

  int `harp_product_update_history`(harp_product *product, const char *executable, int argc, char *argv[])

    Update the history attribute in the product based on the command line parameters. This function will extend the existing product history metadata element with a line containing the current UTC time, the HARP version, and the call that was used to run this program. The command line execution call is constructed based on the argc and argv arguments. The format of the added line is: YYYY-MM-DDThh:mm:ssZ [harp-x.y] args ….

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product for which the history metada should be extended.

      - `executable`: Name of the command line executable (this value is used instead of argv[0]).

      - `argc`: Variable as passed by main().

      - `argv`: Variable as passed by main().

  int `harp_product_verify`(const harp_product *product)

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

    Return

      - `0`, Product verified successfully.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to verify.

  void `harp_product_print`(const harp_product *product, int show_attributes, int show_data, int (*print)(const char*, ...))

    Print a harp_product struct using the specified print function.

    Parameters

      - `product`: Product to print.

      - `show_attributes`: Whether or not to print the attributes of variables.

      - `show_data`: Whether or not to print the data arrays of the variables

      - `print`: Print function to use

  int `harp_product_flatten_dimension`(harp_product *product, harp_dimension_type dimension_type)

    Collapse a given dimension into the time dimension

    Flattening a product for a certain dimension collapses the dimension into the time dimension (i.e. the time dimension and the provided dimension are flattened together). For instance, if a product contains a variable with [num_time,num_longitude,num_latitudes,num_vertical] as dimensions, then flattening for the vertical dimension will result in a variable with [num_time*num_vertical,num_longitudes,num_latitudes] as dimensions.

    The end result of this function is that the time dimension will have grown by a factor equal to the length of the given dimension type and that none of the variables in the product will depend on the given dimension type anymore.

    Independent dimensions and the time dimension cannot be flattened. In the special case that the length of the flattened dimension equals 1, the dimension is just removed for all variables.

    If the dimension length does not equal 1 then the following applies:

    - any variables that depend more than once on the given dimension type will be removed from the product,

    - the index and collocation_index variables will be removed if present, and

    - variables that had the given dimension type but were time independent are first made time dependent

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: HARP product.

      - `dimension_type`: Dimension to use for the flattening.

  int `harp_product_sort`(harp_product *product, int num_variables, const char **variable_name)

    Reorder a dimension for all variables in a product such that the variables with the given names ends up sorted.

    Variables for the provided variable_name list should exist in the product and the variables should be one dimensional variables, all using the same dimension. The dimension that will be reordered is this single dimension of the referenced variables.

    Only up to eight variables can be used for sorting.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: HARP product

      - `num_variables`: Number of variables to use for sorting (1 <= num_variables <= 8)

      - `variable_name`: Names of the variables to use for sorting

  int `harp_product_execute_operations`(harp_product *product, const char *operations)

    Execute one or more operations on a product.

    if one of the operations results in an empty product then the function will immediately return with the empty product (and return code 0) and will not execute any of the remaining actions anymore.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product that the operations should be executed on.

      - `operations`: Operations to execute; should be specified as a semi-colon separated string of operations.

  int `harp_product_rebin_with_axis_bounds_variable`(harp_product *product, harp_variable *target_bounds)

    Rebin all variables in the product to a specified interval grid. The target bounds variable should be an axis bounds variable containing the interval edges (bins) of the target grid (as ‘double’ values). It should be a two-dimensional variable (for a time independent grid) or a three-dimensional variable (for a time dependent grid). The last dimension should be an independent dimension of length 2 (for the lower/upper bound of each interval). The dimension to use for regridding is based on the type of the second to last dimenion of the target grid variable. This function cannot be used to rebin an independent dimension or rebin the time dimension.

    For each variable in the product, a dimension-specific rule based on the variable name will determine how to rebin the variable. For most variables the result will be the interval weighted average of all values overlapping the target interval. Variables that represent an integrated quantity for the rebinned dimension will use an interval weighted sum. For uncertainty variables the first order propagation rules are used (assuming full correlation).

    Variables that depend on the rebinned dimenion but have no unit (or use a string data type) will be removed. Any existing count or weight variables will also be removed.

    All variables that are rebinned are converted to a double data type. Bins that have no overlapping source boundaries will end up with a NaN value.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to rebin.

      - `target_bounds`: Target grid boundaries variable.

  int `harp_product_regrid_with_axis_variable`(harp_product *product, harp_variable *target_grid, harp_variable *target_bounds)

    Resample all variables in the product against a specified grid. The target grid variable should be an axis variable containing the target grid (as ‘double’ values). It should be a one-dimensional variable (for a time independent grid or when regridding in the time dimension) or a two-dimensional variable (for a time dependent grid when not regridding in the time dimension). The dimension to use for regridding is based on the type of the last dimenion of the target grid variable. This function cannot be used to regrid an independent dimension.

    If the target grid variable is two dimensional then its time dimension should match that of the product.

    For each variable in the product a dimension-specific rule based on the variable name will determine how to regrid the variable (point/interval interpolation). If interval interpolation is needed for one of the variables then target boundaries are needed. These can be provided using the optional target_bounds parameter. If this parameter is not provided, the boundaries will be calculated automatically from the target grid (by inter/extrapolating intervals from mid-points).

    The source grid (and bounds) are determined by performing a variable derivation on the product (using the variable name of the target_grid variable).

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to resample.

      - `target_grid`: Target grid variable.

      - `target_bounds`: Target grid boundaries variable (optional).

  int `harp_product_regrid_with_collocated_product`(harp_product *product, harp_dimension_type dimension_type, const char *axis_name, const char *axis_unit, const harp_product *collocated_product)

    Regrid the product’s variables to the target grid of the collocated product.

    This function cannot be used to regrid the time dimension (or an independent dimension).

    Both the product and the collocated product need to have `collocation_index` variables. These collocation indices will be used to determine the matching pairs. For each `collocation_index` value in product there needs to be a matching value in the `collocation_index` variable of collocated_product (but the reverse does not have to be true).

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to regrid.

      - `dimension_type`: Type of dimension that should be regridded.

      - `axis_name`: The name of the variable to use as target grid.

      - `axis_unit`: The unit in which the vertical_axis will be brought for the regridding.

      - `collocated_product`: The product containing the collocated measurements and the target grid for the regridding.

  int `harp_product_regrid_with_collocated_dataset`(harp_product *product, harp_dimension_type dimension_type, const char *axis_name, const char *axis_unit, harp_collocation_result *collocation_result)

    Regrid the product’s variables (from dataset a in the collocation result) to the target grid of collocated products in dataset b.

    This function cannot be used to regrid the time dimension (or an independent dimension).

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to regrid.

      - `dimension_type`: Type of dimension that should be regridded.

      - `axis_name`: The name of the variable to use as target grid.

      - `axis_unit`: The unit in which the vertical_axis will be brought for the regridding.

      - `collocation_result`: The collocation result used to find matching variables. The collocation result is assumed to have the appropriate metadata available for all matches (dataset b).

  int `harp_product_smooth_vertical_with_collocated_product`(harp_product *product, int num_smooth_variables, const char **smooth_variables, const char *vertical_axis, const char *vertical_unit, const harp_product *collocated_product)

    Smooth the product’s variables using the vertical grids, avks and a apriori of the collocated product.

    The product is first fully regridded (using the vertical dimension) to the vertical grid of the averaging kernel (and apriori). Then, the given list of variables is smoothed using the list of AVKs and apriori variables.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to smooth.

      - `num_smooth_variables`: length of smooth_variables.

      - `smooth_variables`: The names of the variables to smooth.

      - `vertical_axis`: The name of the variable to use as a vertical axis (pressure/altitude/etc).

      - `vertical_unit`: The unit in which the vertical_axis will be brought for the regridding.

      - `collocated_product`: The product containing the collocated measurements and the averaging kernel and a-priori.

  int `harp_product_smooth_vertical_with_collocated_dataset`(harp_product *product, int num_smooth_variables, const char **smooth_variables, const char *vertical_axis, const char *vertical_unit, const harp_collocation_result *collocation_result)

    Smooth the product’s variables (from dataset a in the collocation result) using the vertical grids, avks and a apriori of collocated products in dataset b.

    The product is first fully regridded (using the vertical dimension) to the vertical grid of the averaging kernel (and apriori). Then, the given list of variables is smoothed using the list of AVKs and apriori variables.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to smooth.

      - `num_smooth_variables`: length of smooth_variables.

      - `smooth_variables`: The names of the variables to smooth.

      - `vertical_axis`: The name of the variable to use as a vertical axis (pressure/altitude/etc).

      - `vertical_unit`: The unit in which the vertical_axis will be brought for the regridding.

      - `collocation_result`: The collocation result used to locate the matching vertical grids/avks/apriori. The collocation result is assumed to have the appropriate metadata available for all matches (dataset b).

  int `harp_product_get_smoothed_column`(harp_product *product, const char *name, const char *unit, harp_variable *vertical_grid, harp_variable *vertical_bounds, harp_variable *column_avk, harp_variable *apriori, harp_variable **variable)

    Derive vertical column smoothed with column averaging kernel and optional a-priori First a partial column profile will be derived from the product. This partial column profile will be regridded to the column averaging kernel grid. The regridded column profile will then be combined with the column averaging kernel and optional apriori profile to create an integrated smoothed vertical column. All inputs need to be provided as ‘double’ data.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product from which to derive a smoothed integrated vertical column.

      - `name`: Name of the variable that should be created.

      - `unit`: Unit (optional) of the variable that should be created.

      - `vertical_grid`: Variable containing the vertical grid of the column avk.

      - `vertical_bounds`: Variable containing the grid boundaries of the column avk (optional).

      - `column_avk`: Column averaging kernel variable.

      - `apriori`: Apriori profile (optional).

      - `variable`: Pointer to the C variable where the derived HARP variable will be stored.

  int `harp_product_get_smoothed_column_using_collocated_product`(harp_product *product, const char *name, const char *unit, int num_dimensions, const harp_dimension_type *dimension_type, const char *vertical_axis, const char *vertical_unit, const harp_product *collocated_product, harp_variable **variable)

    Derive a vertical column smoothed with column averaging kernel and a-priori from the collocated product

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to regrid.

      - `name`: Name of the variable that should be created.

      - `unit`: Unit (optional) of the variable that should be created.

      - `num_dimensions`: Number of dimensions of the variable that should be created.

      - `dimension_type`: Type of dimension for each of the dimensions of the variable that should be created.

      - `vertical_axis`: The name of the variable to use as a vertical axis (pressure/altitude/etc).

      - `vertical_unit`: The unit in which the vertical_axis will be brought for the regridding.

      - `collocated_product`: The product containing the collocated measurements and the averaging kernel and a-priori.

      - `variable`: Pointer to the C variable where the derived HARP variable will be stored.

  int `harp_product_get_smoothed_column_using_collocated_dataset`(harp_product *product, const char *name, const char *unit, int num_dimensions, const harp_dimension_type *dimension_type, const char *vertical_axis, const char *vertical_unit, const harp_collocation_result *collocation_result, harp_variable **variable)

    Derive a vertical column smoothed with column averaging kernel and a-priori from collocated products in dataset b

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `product`: Product to regrid.

      - `name`: Name of the variable that should be created.

      - `unit`: Unit (optional) of the variable that should be created.

      - `num_dimensions`: Number of dimensions of the variable that should be created.

      - `dimension_type`: Type of dimension for each of the dimensions of the variable that should be created.

      - `vertical_axis`: The name of the variable to use as a vertical axis (pressure/altitude/etc).

      - `vertical_unit`: The unit in which the vertical_axis will be brought for the regridding.

      - `collocation_result`: The collocation result used to find matching variables. The collocation result is assumed to have the appropriate metadata available for all matches (dataset b).

      - `variable`: Pointer to the C variable where the derived HARP variable will be stored.

  int `harp_import`(const char *filename, const char *operations, const char *options, harp_product **product)

    Import a product from a file.

    This will first try to import the file as an HDF4, HDF5, or netCDF file that complies to the HARP Data Format. If the file is not stored using the HARP format then it will try to import it using one of the available ingestion modules. The options parameter is optional (can be NULL) and describes the ingestion options. The parameter is only applicable if the file is not already using the HARP format and needs to be converted using one of the ingestion modules. The operations parameter is optional (can be NULL) and provides the list of operations that will be performed as part of the import. Some operations, such as filters, can already be performed as part of an import and this may thus be faster than using a harp_product_execute_operations() after a full import of the product.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `[in] filename`: Path to the file that is to be imported.

      - `[in] operations`: string (optional) containing actions to apply as part of the import; should be specified as a semi-colon separated string of operations.

      - `[in] options`: Ingestion module specific options (optional); should be specified as a semi-colon separated string of key=value pair; only used if the file is not in HARP format.

      - `[out] product`: Pointer to a location where a pointer to the ingested product will be stored.

  int `harp_import_test`(const char *filename, int (*print)(const char*, ...))

    Test import of a product.

    If the product is a HARP product then verify that the product is a HARP compliant netCDF/HDF4/HDF5 product. Otherwise, try to import the product using an applicable ingestion module and test the ingestion for all possible ingestion options. Results are printed using the provided print function. The print function parameter should be a function that resembles printf().

    Return

      - `0`, Success.

      - `1`, Import failed (error is already printed, harp_errno should be ignored).

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `[in] filename`: Filename of the product to import.

      - `[in] print`: Reference to a printf compatible function.

  int `harp_import_product_metadata`(const char *filename, const char *options, harp_product_metadata **new_metadata)

    Retrieve global attributes from a product file.

    This function retrieves the product metadata without performing a full import.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `filename`: Path to the file for which to retrieve global attributes.

      - `options`: Ingestion module specific options (optional); should be specified as a semi-colon separated string of key=value pair; only used if the file is not in HARP format.

      - `new_metadata`: Pointer to the variable where the metadata should be stored.

  int `harp_export`(const char *filename, const char *export_format, const harp_product *product)

    Export HARP product to a file.

    Export product to an HDF4, HDF5, or netCDF file that complies to the HARP Data Format.

    Return

      - `0`, Success.

      - `-1`, Error occurred (check harp_errno).

    Parameters

      - `filename`: Path to the file to which the product is to be exported.

      - `export_format`: Either “hdf4”, “hdf5”, or “netcdf”.

      - `product`: Product that should be exported to file.

  struct `harp_product_struct`
    #include <harp.h>

    HARP Product struct

    Public Members

    long `dimension`[`HARP_NUM_DIM_TYPES`]

      length of each dimension (0 for unused dimensions)

    int `num_variables`

      number of variables in this product

    harp_variable **`variable`

      pointers to the variables

    char *`source_product`

      identifier of the product the HARP product originates from

    char *`history`

      value for the ‘history’ global attribute