/// \brief Construct an alignment between multiple lists of residues by pulling together residues of the same name.
///
/// Does this code necessarily need to construct an alignment
/// (as opposed to just identifying the coordinates to superpose)?
///
/// Advantages:
/// - It helps to illustrate how things are being superposed
/// - It makes it easier to check for (and disallow) conflicts in the ordering of residues
/// - It makes it possible to SSAP-score the alignment and then perform a weighted superposition
///
/// Disadvantages:
/// - It makes things a bit more complicated
/// - Any decisions that have to be taken about how to align the non-matching residues are arbitrary
/// (but may misinterpreted as meaningful).
///
/// Where there are choices about which entry's position to add first:
/// - add the longest entry's position first (helps to give consistent answers for testing)
/// - add the first entry's position first
alignment residue_name_aligner::residue_name_align(const residue_name_vec_vec &arg_residue_lists ///< TODOCUMENT
) {
// Check that there is at least one list
const str_vec_vec::size_type num_lists = arg_residue_lists.size();
if (num_lists < 1) {
BOOST_THROW_EXCEPTION(invalid_argument_exception("Cannot residue_name_align() zero residue lists"));
}
// Check that at least one of the lists is not empty
// \todo Change this to use C++11 any_of() and use a lambda to check for not empty
bool found_non_empty = false;
for (const residue_name_vec &arg_residue_list : arg_residue_lists) {
if ( ! arg_residue_list.empty() ) {
found_non_empty = true;
}
}
if ( ! found_non_empty ) {
BOOST_THROW_EXCEPTION(invalid_argument_exception("Cannot residue_name_align() residue lists that are all empty"));
}
// Build a vector of residue_name_align_map objects, one for each arg_residue_list
vector<residue_name_align_map> maps;
maps.reserve(num_lists);
for (const residue_name_vec &residue_list : arg_residue_lists) {
maps.push_back( residue_name_align_map( make_residue_name_align_map( residue_list ) ) );
}
// Data structures to create the alignment:
size_vec next_index_to_add_for_lists(num_lists, 0);
opt_aln_posn_vec_vec raw_alignment_data( num_lists );
// Do the actual work of building an alignment
bool more_to_do = true;
while (more_to_do) {
more_to_do = false;
// This is made a bit more complicated to ensure that the longer entry's position
// is inserted first where there is a choice
bool found_non_skipping = false;
size_t entry_of_non_skipping = 0;
// Search to find an entry for which a new entry can be inserted into the alignment
for (size_t entry_ctr = 0; entry_ctr < num_lists; ++entry_ctr) {
// If this entry is complete, then continue to the next entry
// otherwise, grab the next residue string for this entry
// and record that there's more_to_do
const size_t &next_index_to_add = next_index_to_add_for_lists[entry_ctr];
if ( next_index_to_add >= arg_residue_lists[ entry_ctr ].size() ) {
continue;
}
const residue_name &the_res_name = arg_residue_lists[entry_ctr][next_index_to_add];
more_to_do = true;
// If a better or equal non-skipping has already been found (ie for an entry that's at least as long as this one)
// then no point considering this one so continue to next pass of loop
if (found_non_skipping && arg_residue_lists[entry_of_non_skipping].size() >= arg_residue_lists[entry_ctr].size()) {
continue;
}
// Find which entries have equivalent residues and the indices of those equivalents
opt_aln_posn_vec equivalent_indices;
equivalent_indices.reserve( num_lists );
for (const residue_name_align_map &map : maps) {
const opt_aln_posn value = contains_residue_name( map, the_res_name ) ? opt_aln_posn( get_index_of_residue_name( map, the_res_name ) )
: opt_aln_posn( none );
equivalent_indices.push_back( value );
}
// Check whether inserting this row of of equivalents would involve skipping anything
bool found_skip_here = false;
for (size_t entry_check_ctr = 0; entry_check_ctr < num_lists; ++entry_check_ctr) {
const opt_aln_posn &position = equivalent_indices[entry_check_ctr];
if ( position && *position != next_index_to_add_for_lists[ entry_check_ctr ] ) {
if ( *position < next_index_to_add_for_lists[entry_check_ctr]) {
BOOST_THROW_EXCEPTION(
invalid_argument_exception(
"Whilst aligning residue names, residue " + lexical_cast<string>( the_res_name )
+ " is out of order (in entry " + lexical_cast<string>( entry_ctr )
+ " and entry " + lexical_cast<string>( entry_check_ctr )
+ " around indices " + lexical_cast<string>( *position )
+ " and " + lexical_cast<string>( next_index_to_add_for_lists[ entry_check_ctr ] )
+ ")"
)
);
}
found_skip_here = true;
break;
}
}
// If we've found a skip here then it's better than before If we've found a better skip than before then record it
if ( ! found_skip_here ) {
entry_of_non_skipping = entry_ctr;
found_non_skipping = true;
}
else {
}
}
// If this entry is ready to be inserted, then proceed and break out of this loop
if ( found_non_skipping ) {
const residue_name &the_res_name = arg_residue_lists[entry_of_non_skipping][next_index_to_add_for_lists[entry_of_non_skipping]];
// Find which entries have equivalent residues
bool_deq equivalent_presences;
for (const residue_name_align_map &map : maps) {
equivalent_presences.push_back( contains_residue_name( map, the_res_name ) );
}
// Insert the new positions and increment the relevant indices in next_index_to_add_for_lists
for (size_t entry_check_ctr = 0; entry_check_ctr < num_lists; ++entry_check_ctr) {
const bool &should_insert_entry = equivalent_presences[ entry_check_ctr ];
const opt_aln_posn value = should_insert_entry ? next_index_to_add_for_lists[ entry_check_ctr ]
: opt_aln_posn( none );
raw_alignment_data[ entry_check_ctr ].push_back( value );
if ( should_insert_entry ) {
++( next_index_to_add_for_lists[ entry_check_ctr ] );
}
}
}
if ( more_to_do && ! found_non_skipping ) {
BOOST_THROW_EXCEPTION(invalid_argument_exception("Unable to align residue names, this probably means the residue ordering is not consistent"));
}
}
// Create and return an alignment from the data
return alignment( raw_alignment_data );
}
/// \brief Checks that residue_name_aligner::residue_name_align() does the correct thing for all permutations of the residue lists.
///
/// This should be accessed via check_residue_name_aligner_results() or check_residue_name_aligner_throws()
///
/// This subroutine is mostly ready to handle more than two lists.
///
/// \todo modify the actual call to residue_name_aligner::residue_name_align() to handle multiple lists
/// (after that subroutine has been altered to handle multiple lists)
void do_check_residue_name_aligner(const residue_name_vec_vec &arg_residue_lists,
const bool_deq_vec &arg_correct_presence_lists,
const size_vec_vec &arg_correct_answer_lists,
const bool &arg_should_throw
) {
const size_t num_lists = arg_residue_lists.size();
BOOST_REQUIRE_EQUAL(num_lists, 2_z); /// This code isn't yet able to process more than two at a time
if (!arg_should_throw) {
BOOST_REQUIRE_EQUAL(num_lists, arg_correct_presence_lists.size());
BOOST_REQUIRE_EQUAL(num_lists, arg_correct_answer_lists.size());
}
// Construct a vector containing the indices of the lists
size_vec permutation_indices(num_lists, 0);
for (size_t index_ctr = 0; index_ctr < num_lists; ++index_ctr) {
permutation_indices[index_ctr] = index_ctr;
}
// Loop over the permutations of the indices
do {
// If these residue lists should cause residue_name_aligner::residue_name_align() to throw then check they do
if (arg_should_throw) {
BOOST_CHECK_THROW(
residue_name_aligner::residue_name_align(
{ arg_residue_lists[ permutation_indices[ 0 ] ],
arg_residue_lists[ permutation_indices[ 1 ] ] }
),
invalid_argument_exception
);
}
// Otherwise check the results from residue_name_aligner::residue_name_align()
else {
// Construct an alignment from this permutation of residue lists
const alignment my_alignment = residue_name_aligner::residue_name_align(
{ arg_residue_lists[permutation_indices[ 0 ]],
arg_residue_lists[permutation_indices[ 1 ]] }
);
const alignment::size_type num_positions = my_alignment.length();
// Check each of the alignment entries in turn
for (size_t index_ctr = 0; index_ctr < num_lists; ++index_ctr) {
// Grab the correct answer list under the current permutation
const size_t permutation_index = permutation_indices[index_ctr];
const bool_deq &correct_presence_list = arg_correct_presence_lists[permutation_index];
const size_vec &correct_answer_list = arg_correct_answer_lists[permutation_index];
const size_t correct_answer_size = correct_answer_list.size();
// Check that the number of positions match
BOOST_CHECK_EQUAL(correct_answer_size, num_positions);
// Check that each of the positions in the alignment match what is expected
for (size_t position_ctr = 0; position_ctr < min(correct_answer_size, num_positions); ++position_ctr) {
const aln_posn_opt position = my_alignment.position_of_entry_of_index( index_ctr, position_ctr );
const bool has_position = static_cast<bool>( position );
BOOST_CHECK_EQUAL( correct_presence_list[position_ctr], has_position );
if ( position ) {
BOOST_CHECK_EQUAL(correct_answer_list[position_ctr], *position );
}
}
}
}
} while ( next_permutation( permutation_indices ) );
}