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
- 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
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
void harp_collocation_result_delete(harp_collocation_result *collocation_result)
Remove a collocation result set
- 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
- Parameters:
collocation_result – Result set that will be sorted in place.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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
- Parameters:
collocation_result – Result set that will be sorted in place.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
int harp_collocation_result_sort_by_collocation_index(harp_collocation_result *collocation_result)
Sort the collocation result pairs by collocation index
- Parameters:
collocation_result – Result set that will be sorted in place.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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.
- Parameters:
collocation_result – Result set that will be filtered in place.
source_product – source product reference from dataset A that should be filtered on.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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.
- Parameters:
collocation_result – Result set that will be filtered in place.
source_product – source product reference from dataset B that should be filtered on.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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.
- 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.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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
- 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
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
int harp_collocation_result_remove_pair_at_index(harp_collocation_result *collocation_result, long index)
Remove collocation result entry from a result set
- 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
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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.
- 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.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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.
- Parameters:
collocation_result_filename – Full file path to the csv file.
collocation_result – Collocation result set that will be written to file.
- Returns:
0, Success.-1, Error occurred (check harp_errno).
-
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 harp_collocation_pair