aboutsummaryrefslogtreecommitdiff
path: root/libcrystfel/src
diff options
context:
space:
mode:
authorThomas White <taw@physics.org>2021-02-05 16:47:32 +0100
committerThomas White <taw@physics.org>2021-02-05 16:47:32 +0100
commitff2efa35e83f9973b90d9bca749d6da585158b23 (patch)
treed431f2865d3dd6654846340dd35d775db8691650 /libcrystfel/src
parent252e2e13bded09fd3cd0fd3a1112605b2b97458a (diff)
Documentation for new FoM API
Diffstat (limited to 'libcrystfel/src')
-rw-r--r--libcrystfel/src/fom.c119
-rw-r--r--libcrystfel/src/fom.h24
2 files changed, 134 insertions, 9 deletions
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 <reflist.h>
#include <symmetry.h>
+/**
+ * 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,