Collocation
-
group
harp_collocation
The HARP Collocation module contains the functionality that deals with collocation two datasets of products. The two datasets are refered 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 resultdifference_variable_name
: An array of variable names describing the type of difference for each calculated differencedifference_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.
-
static int
find_collocation_pair_for_collocation_index
(harp_collocation_result *collocation_result, long collocation_index, long *index)
-
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 extendedcollocation_index
: Unique index of the pair in the overall collocation resultsource_product_a
: Name of the source_product attribute of the product from dataset Aindex_a
: Value of the index variable for the matching sample in the product from dataset Asource_product_b
: Name of the source_product attribute of the product from dataset Bindex_b
: Value of the index variable for the matching sample in the product from dataset Bnum_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 entryindex
: 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
-
typedef struct harp_collocation_pair_struct