# Collocation

group `harp_collocation`

  The HARP Collocation module contains the functionality that deals with collocation two datasets of products. The two datasets are referred to as dataset A (primary) and dataset B (secondary). The result of a collocation is a list of pairs. Each pair references a measurement from dataset A (using the source product name and measurement index within that product) and a measurement from dataset B. Each collocation pair also gets a unique collocation_index sequence number. For each collocation criteria used in the matchup the actual difference is stored as part of the pair as well. Collocation results can be written to and read from a csv file.

  Typedefs

  typedef struct harp_collocation_pair_struct `harp_collocation_pair`
  typedef struct harp_collocation_result_struct `harp_collocation_result`

  Functions

  int `harp_collocation_result_new`(harp_collocation_result **new_collocation_result, int num_differences, const char **difference_variable_name, const char **difference_unit)

    Create a new collocation result set

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `new_collocation_result`: Pointer to the C variable where the new result set will be stored.
      - `num_differences`: The number of differences that have been calculated per pair for the collocation result
      - `difference_variable_name`: An array of variable names describing the type of difference for each calculated difference
      - `difference_unit`: An array of units for each calculated difference
  void `harp_collocation_result_delete`(harp_collocation_result *collocation_result)

    Remove a collocation result set

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be removed.
  int `harp_collocation_result_sort_by_a`(harp_collocation_result *collocation_result)

    Sort the collocation result pairs by dataset A Results will be sorted first by product index of A and then by sample index of A

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be sorted in place.
  int `harp_collocation_result_sort_by_b`(harp_collocation_result *collocation_result)

    Sort the collocation result pairs by dataset B Results will be sorted first by product index of B and then by sample index of B

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be sorted in place.
  int `harp_collocation_result_sort_by_collocation_index`(harp_collocation_result *collocation_result)

    Sort the collocation result pairs by collocation index

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be sorted in place.
  int `harp_collocation_result_filter_for_source_product_a`(harp_collocation_result *collocation_result, const char *source_product)

    Filter collocation result set for a specific product from dataset A Only results that contain the referenced source product will be retained.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be filtered in place.
      - `source_product`: source product reference from dataset A that should be filtered on.
  int `harp_collocation_result_filter_for_source_product_b`(harp_collocation_result *collocation_result, const char *source_product)

    Filter collocation result set for a specific product from dataset B Only results that contain the referenced source product will be retained.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be filtered in place.
      - `source_product`: source product reference from dataset B that should be filtered on.
  int `harp_collocation_result_filter_for_collocation_indices`(harp_collocation_result *collocation_result, long num_indices, int32_t *collocation_index)

    Filter collocation result set for the specified list of collocation indices. The collocation result pairs will be sorted according to the order in the provided collocation_index parameter. If a collocation index cannot be found in the collocation_result set then an error will be thrown.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be filtered in place.
      - `num_indices`: Number of items in the collocation_index parameter.
      - `collocation_index`: Array of collocation index values to match against the collocation_result set.
  int `harp_collocation_result_add_pair`(harp_collocation_result *collocation_result, long collocation_index, const char *source_product_a, long index_a, const char *source_product_b, long index_b, int num_differences, const double *difference)

    Add collocation result entry to a result set

    Note
      this function will not check for uniqueness of the collocation_index values in the resulting set
    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set that will be extended
      - `collocation_index`: Unique index of the pair in the overall collocation result
      - `source_product_a`: Name of the source_product attribute of the product from dataset A
      - `index_a`: Value of the index variable for the matching sample in the product from dataset A
      - `source_product_b`: Name of the source_product attribute of the product from dataset B
      - `index_b`: Value of the index variable for the matching sample in the product from dataset B
      - `num_differences`: Number of calculated differences (should equal the number of differences with which the collocation result was initialized)
      - `difference`: Array of difference values
  int `harp_collocation_result_remove_pair_at_index`(harp_collocation_result *collocation_result, long index)

    Remove collocation result entry from a result set

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result`: Result set from which to remove the entry
      - `index`: Zero-based index in the collocation result set of the entry that should be removed
  int `harp_collocation_result_read`(const char *collocation_result_filename, harp_collocation_result **new_collocation_result)

    Read collocation result set from a csv file The csv file should follow the HARP format for collocation result files.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result_filename`: Full file path to the csv file.
      - `new_collocation_result`: Pointer to the C variable where the new result set will be stored.
  int `harp_collocation_result_write`(const char *collocation_result_filename, harp_collocation_result *collocation_result)

    Read collocation result set to a csv file The csv file will follow the HARP format for collocation result files.

    Return
      - `0`, Success.
      - `-1`, Error occurred (check harp_errno).
    Parameters
      - `collocation_result_filename`: Full file path to the csv file.
      - `collocation_result`: Collocation result set that will be written to file.
  void `harp_collocation_result_swap_datasets`(harp_collocation_result *collocation_result)

    Swap the columns of this collocation result inplace.

    This swaps datasets A and B (such that A becomes B and B becomes A).

    Parameters
      - `collocation_result`: Collocation result whose datasets should be swapped.
  struct `harp_collocation_pair_struct`
    #include <harp.h>

    Entry for a single matched pair for a collocation between a dataset A and dataset B

  struct `harp_collocation_result_struct`
    #include <harp.h>

    HARP Collocation result