From ff2efa35e83f9973b90d9bca749d6da585158b23 Mon Sep 17 00:00:00 2001 From: Thomas White Date: Fri, 5 Feb 2021 16:47:32 +0100 Subject: Documentation for new FoM API --- libcrystfel/src/fom.c | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++ libcrystfel/src/fom.h | 24 ++++++---- 2 files changed, 134 insertions(+), 9 deletions(-) (limited to 'libcrystfel') diff --git a/libcrystfel/src/fom.c b/libcrystfel/src/fom.c index 2d3623ea..3e734bda 100644 --- a/libcrystfel/src/fom.c +++ b/libcrystfel/src/fom.c @@ -43,6 +43,10 @@ #include "reflist.h" #include "reflist-utils.h" +/** + * \file fom.h + */ + struct fom_context { enum fom_type fom; @@ -306,6 +310,11 @@ static int add_to_fom(struct fom_context *fctx, } +/** + * Calculates the overall value for the %fom_context + * + * You must have previously called fom_calculate() + */ double fom_overall_value(struct fom_context *fctx) { double overall_num = INFINITY; @@ -477,6 +486,10 @@ double fom_overall_value(struct fom_context *fctx) } +/** + * Calculates the figure of merit for the specified shell number. + * You must have previously called fom_calculate() + */ double fom_shell_value(struct fom_context *fctx, int i) { double cc; @@ -552,6 +565,16 @@ double fom_shell_value(struct fom_context *fctx, int i) } +/** + * \param rmin: The minimum value of 1/d, in m^-1 + * \param rmax: The maximum value of 1/d, in m^-1 + * \param nshells: The number of shells to use + * + * Create a %fom_shells structure for the specified minimum and maximum + * resolution limits + * + * Returns the %fom_shells structure, or NULL on error. + */ struct fom_shells *fom_make_resolution_shells(double rmin, double rmax, int nshells) { @@ -594,6 +617,13 @@ struct fom_shells *fom_make_resolution_shells(double rmin, double rmax, } +/** + * \param s: A %fom_shells structure + * \param i: The shell number + * + * Returns the value of 1/d at the middle of the shell, + * i.e. the mean of the minimum and maximum 1/d values for the shell + */ double fom_shell_centre(struct fom_shells *s, int i) { return s->rmins[i] + (s->rmaxs[i] - s->rmins[i])/2.0; @@ -856,6 +886,28 @@ static int is_single_list(enum fom_type fom) } +/** + * \param list1: A %RefList + * \param list2: A %RefList + * \param cell: A %UnitCell + * \param shells: A %fom_shells structure + * \param fom: The figure of merit to calculate + * \param noscale: Non-zero to disable scaline of reflection lists + * \param sym: The symmetry of \p list1 and \p list2. + * + * Calculates the specified figure of merit, comparing the two reflection lists. + * + * The \p cell and \p sym must match both reflection lists. You should also have + * called fom_select_reflection_pairs() to pre-process the lists. + * + * If the figure of merit does not involve comparison (e.g. %FOM_SNR), + * then \p list1 will be used. In this case, \p list2 and \p noscale will be + * ignored. Use fom_select_reflections() instead of fom_select_reflection_pairs() + * in this case. + * + * \returns a %fom_context structure. Use fom_shell_value() et al., to + * extract the actual figure of merit values. + */ struct fom_context *fom_calculate(RefList *list1, RefList *list2, UnitCell *cell, struct fom_shells *shells, enum fom_type fom, int noscale, const SymOpList *sym) @@ -972,6 +1024,28 @@ struct fom_context *fom_calculate(RefList *list1, RefList *list2, UnitCell *cell } +/** + * \param list1: The first input %RefList + * \param list2: The second input %RefList + * \param plist1_acc: Pointer to location for accepted list + * \param plist2_acc: Pointer to location for accepted list + * \param cell: A %UnitCell + * \param sym: The symmetry of \p raw_list + * \param anom: Non-zero if you will calculate a FoM for anomalous signal + * \param rmin_fix: If positive, minimum resolution to use + * \param rmax_fix: If positive, maximum resolution to use + * \param sigma_cutoff: Minimum I/sigI value + * \param ignore_negs: Non-zero to filter out negative intensities + * \param zero_negs: Non-zero to set negative intensities to zero + * \param mul_cutoff: Minimum number of measurements per reflection + * + * Selects reflections suitable for use with fom_calculate(). + * + * Use -INFINITY for \p sigma_cutoff to disable the check. + * Set \p mul_cutoff to zero to disable the check. + * + * \returns a %fom_rejections structure with the counts of reflections. + */ struct fom_rejections fom_select_reflection_pairs(RefList *list1, RefList *list2, RefList **plist1_acc, RefList **plist2_acc, @@ -1163,6 +1237,23 @@ struct fom_rejections fom_select_reflection_pairs(RefList *list1, RefList *list2 } +/** + * \param raw_list: The input %RefList + * \param plist_acc: Pointer to location for accepted list + * \param cell: A %UnitCell + * \param sym: The symmetry of \p raw_list + * \param rmin_fix: If positive, minimum resolution to use + * \param rmax_fix: If positive, maximum resolution to use + * \param sigma_cutoff: Minimum I/sigI value + * \param ignore_negs: Non-zero to filter out negative intensities + * \param zero_negs: Non-zero to set negative intensities to zero + * \param mul_cutoff: Minimum number of measurements per reflection + * + * Use -INFINITY for \p sigma_cutoff to disable the check. + * Set \p mul_cutoff to zero to disable the check. + * + * \returns a %fom_rejections structure with the counts of reflections. + */ struct fom_rejections fom_select_reflections(RefList *raw_list, RefList **plist_acc, UnitCell *cell, SymOpList *sym, @@ -1251,6 +1342,11 @@ struct fom_rejections fom_select_reflections(RefList *raw_list, } +/** + * \param fctx: A %fom_context structure + * + * \returns the total number of unique reflections + */ int fom_overall_num_reflections(struct fom_context *fctx) { int i; @@ -1263,12 +1359,26 @@ int fom_overall_num_reflections(struct fom_context *fctx) } +/** + * \param fctx: A %fom_context structure + * \param i: Shell number + * + * \returns the number of unique reflections in the shell + */ int fom_shell_num_reflections(struct fom_context *fctx, int i) { return fctx->cts[i]; } +/** + * \param fctx: A %fom_context structure + * + * This must only be called on a %fom_context for %FOM_COMPLETENESS. + * + * \returns the total number of reflections possible in all shells, taking into + * account symmetry and lattice absences, but not screw axis/glide place absences. + */ int fom_overall_num_possible(struct fom_context *fctx) { int i; @@ -1283,6 +1393,15 @@ int fom_overall_num_possible(struct fom_context *fctx) } +/** + * \param fctx: A %fom_context structure + * \param i: Shell number + * + * This must only be called on a %fom_context for %FOM_COMPLETENESS. + * + * \returns the number of reflections possible in the shell, taking into account + * symmetry and lattice absences, but not screw axis/glide place absences. + */ int fom_shell_num_possible(struct fom_context *fctx, int i) { assert(fctx->fom == FOM_COMPLETENESS); diff --git a/libcrystfel/src/fom.h b/libcrystfel/src/fom.h index fae8748d..c2a340a4 100644 --- a/libcrystfel/src/fom.h +++ b/libcrystfel/src/fom.h @@ -38,19 +38,25 @@ #include #include +/** + * Contains counts of rejected reflections + */ struct fom_rejections { - int common; - int low_snr; - int negative_deleted; - int negative_zeroed; - int few_measurements; - int outside_resolution_range; - int no_bijvoet; - int centric; - int nan_inf_value; + int common; /**< Number of common reflection pairs accepted */ + int low_snr; /**< Reflections with I/sigI too low */ + int negative_deleted; /**< Negative intensities which were deleted */ + int negative_zeroed; /**< Negative intensities which were set to zero */ + int few_measurements; /**< Reflections with too few measurements */ + int outside_resolution_range; /**< Reflections outside resolution range */ + int no_bijvoet; /**< Reflections with no Bijvoet partner */ + int centric; /**< Reflections which are centric */ + int nan_inf_value; /**< Reflections with NaN or infinite intensity */ }; +/** + * An enumeration of possible figures of merit to calculate + */ enum fom_type { FOM_R1I, -- cgit v1.2.3