Add CMC sorting criteria detailed help

build-test-data/map-clusters/help_usage

@@ -32,6 +32,9 @@ Output:
   --summarise-to-file <file>            Print a summary of the renumbering to file <file>
   --print-entry-results                 Output the entry (domain)-level mapping results
 
+Detailed help:
+  --sorting-help                        Show the criteria for sorting unmapped clusters
+
 The input cluster-membership data should contain lines like:
 
 cluster_name domain_id

source/cluster/clustmap_options.cpp

@@ -24,6 +24,8 @@
 
 using namespace cath;
 using namespace cath::clust;
+using namespace cath::opts;
+using namespace std::literals::string_literals;
 
 using boost::algorithm::join;
 using boost::none;
@@ -34,6 +36,13 @@ using std::string;
 /// The name of the program that uses this executable_options
 const string clustmap_options::PROGRAM_NAME("cath-map-clusters");
 
+/// \brief Get the options for the "Detailed Help" block
+str_str_str_pair_map clustmap_options::detail_help_spec() {
+	return {
+		{ "sorting-help", { "Show the criteria for sorting unmapped clusters", get_cmc_sorting_criteria_help_string() } },
+	};
+}
+
 /// \brief Get the name of the program that uses this executable_options
 string clustmap_options::do_get_program_name() const {
 	return PROGRAM_NAME;
@@ -59,6 +68,17 @@ positional_options_description clustmap_options::get_positional_options() {
 /// \returns Any error/help string arising from the newly specified options
 ///          or an empty string if there aren't any
 str_opt clustmap_options::do_get_error_or_help_string() const {
+	// If detailed help was requested, then provide it
+	if ( the_detail_help_ob.has_help_string() ) {
+		return the_detail_help_ob.help_string();
+	}
+
+	const variables_map &local_vm = get_variables_map();
+
+	if ( ! specifies_option( local_vm, clustmap_input_options_block::PO_WORKING_CLUSTMEMB_FILE ) ) {
+		return "Must specify an input file"s;
+	}
+
 	const bool     read_batches_from_input = get_clustmap_input_spec().get_read_batches_from_input();
 	const path_opt map_from_clustmemb_file = get_clustmap_input_spec().get_map_from_clustmemb_file();
 
@@ -70,8 +90,6 @@ str_opt clustmap_options::do_get_error_or_help_string() const {
 			+ ")";
 	}
 
-	const variables_map &local_vm = get_variables_map();
-
 	if ( specified_clust_thresh_options( local_vm ) && ! map_from_clustmemb_file && ! read_batches_from_input ) {
 		return "Cannot specify mapping threshold options (--"
 			+ join( clust_thresh_option_names(), ", --" )
@@ -125,10 +143,11 @@ Renumber any clusters with no equivalents.)";
 }
 
 /// \brief Ctor, which initialises the detail_help_ob and adds the options_blocks to the parent executable_options
-clustmap_options::clustmap_options() {
-	super::add_options_block( the_input_ob   );
-	super::add_options_block( the_mapping_ob );
-	super::add_options_block( the_output_ob  );
+clustmap_options::clustmap_options() : the_detail_help_ob( detail_help_spec() ) {
+	super::add_options_block( the_input_ob       );
+	super::add_options_block( the_mapping_ob     );
+	super::add_options_block( the_output_ob      );
+	super::add_options_block( the_detail_help_ob );
 }
 
 /// \brief Getter for the spec of the cath-map-clusters input options_block
@@ -145,3 +164,14 @@ const clust_mapping_spec & clustmap_options::get_clust_mapping_spec() const {
 const clustmap_output_spec & clustmap_options::get_clustmap_output_spec() const {
 	return the_output_ob.get_clustmap_output_spec();
 }
+
+/// \brief Return the string containing help on CMC sorting criteria
+string cath::clust::get_cmc_sorting_criteria_help_string() {
+	return R"(The sorting criteria for new, unmapped clusters are:
+
+ * Descending on sum over domains of sqrt(total_dom_length) (ie clusters with more/longer sequences come earlier, with more emphasis on having more sequences)
+ * Descending on number of sequences (ie clusters with more sequences come first)
+ * Ascending on average mid-point index (ie clusters with domains earlier in their sequences come first)
+ * Ascending on first domain ID
+)";
+}

source/cluster/clustmap_options.hpp

@@ -25,6 +25,7 @@
 #include "cluster/options/options_block/clustmap_input_options_block.hpp"
 #include "cluster/options/options_block/clustmap_output_options_block.hpp"
 #include "options/executable/executable_options.hpp"
+#include "options/options_block/detail_help_options_block.hpp"
 
 #include <iosfwd>
 
@@ -38,6 +39,8 @@ namespace cath {
 		private:
 			using super = opts::executable_options;
 
+			static std::map<std::string, str_str_pair> detail_help_spec();
+
 			static const std::string STANDARD_USAGE_ERROR_STRING;
 
 			/// \brief The cath-resolve-hits input options_block
@@ -49,6 +52,9 @@ namespace cath {
 			/// \brief The cath-resolve-hits output options_block
 			clustmap_output_options_block        the_output_ob;
 
+			/// \brief The detailed help options_block
+			opts::detail_help_options_block      the_detail_help_ob;
+
 			std::string do_get_program_name() const final;
 			boost::program_options::positional_options_description get_positional_options() final;
 			str_opt do_get_error_or_help_string() const final;
@@ -69,6 +75,8 @@ namespace cath {
 			static const std::string PROGRAM_NAME;
 		};
 
+		std::string get_cmc_sorting_criteria_help_string();
+
 		// std::string get_clustmap_raw_format_help_string();
 		// std::string get_clustmap_cath_rules_help_string();
 

source/cluster/options/options_block/clustmap_input_options_block.cpp

@@ -26,7 +26,6 @@ using namespace cath;
 using namespace cath::clust;
 using namespace cath::common;
 using namespace cath::opts;
-using namespace std::literals::string_literals;
 
 using boost::filesystem::path;
 using boost::program_options::bool_switch;
@@ -109,11 +108,8 @@ void clustmap_input_options_block::do_add_hidden_options_to_description(options_
 
 /// \brief Generate a description of any problem that makes the specified clustmap_input_options_block invalid
 ///        or none otherwise
-str_opt clustmap_input_options_block::do_invalid_string(const variables_map &arg_variables_map ///< The variables map, which options_blocks can use to determine which options were specified, defaulted etc
+str_opt clustmap_input_options_block::do_invalid_string(const variables_map &/*arg_variables_map*/ ///< The variables map, which options_blocks can use to determine which options were specified, defaulted etc
                                                         ) const {
-	if ( ! specifies_option( arg_variables_map, PO_WORKING_CLUSTMEMB_FILE ) ) {
-		return "Must specify an input file"s;
-	}
 	return get_invalid_description( get_clustmap_input_spec() );
 }