Enable access to MMalign from USalign

This is all done on the C++ level, so no intermediate files are
required. Until proper testing, this features must be considered
experimental.

modules/bindings/doc/tmtools.rst

@@ -24,9 +24,7 @@ around USalign as published in:
   (2022) Nat Methods
 
 The advantage is that no intermediate files must be generated, a wrapper on the
-c++ layer is used instead. However, only the basic TM-align superposition between
-single chains is available.
-
+c++ layer is used instead. 
 
 
 Distance measures used by TMscore
@@ -161,3 +159,56 @@ generated in order to call the executable.
   :raises:              :class:`ost.Error` if pos1 and seq1, pos2 and seq2 
                         respectively are not consistent in size.
 
+For higher order complexes, ost provides access to the MMalign functionality
+from USalign. This corresponds to calling USalign with the preferred way of
+comparing full biounits:
+
+.. code-block:: bash
+
+  USalign mdl.pdb ref.pdb -mm 1 -ter 0
+
+
+.. class:: MMAlignResult(rmsd, tm_score, transform, aligned_length, alignments,\
+                         ent1_mapped_chains, ent2_mapped_chains)
+
+  All parameters of the constructor are available as attributes of the class
+
+  :param rmsd:          RMSD of the superposed residues
+  :param tm_score:      TMScore of the superposed residues
+  :param aligned_length: Number of superposed residues
+  :param transform:     Transformation matrix to superpose mdl onto reference 
+  :param alignments:    Alignments of all mapped chains, with first sequence
+                        being from ent1 and second sequence from ent2
+  :param ent1_mapped_chains: All mapped chains from ent1
+  :param ent2_mapped_chains: The respective mapped chains from ent2
+  :type rmsd:           :class:`float`
+  :type tm_score:       :class:`float`
+  :type aligned_length: :class:`int`
+  :type transform:      :class:`geom.Mat4`
+  :type alignments:     :class:`ost.seq.AlignmentList`
+  :type ent1_mapped_chains: :class:`ost.StringList` 
+  :type ent2_mapped_chains: :class:`ost.StringList`
+
+.. method:: WrappedMMAlign(ent1, ent2, [fast=False])
+
+  Takes two entity views and runs MMalign with *ent2* as reference.
+  The positions and sequences are directly extracted from the chain
+  residues for every residue that fulfills:
+  
+    * peptide linking and valid CA atom OR nucleotide linking and valid C3'
+      atom
+    * valid one letter code(no '?')
+
+  The function automatically identifies whether the chains consist of peptide
+  or RNA residues. An error is raised if the two types are mixed in the same
+  chain.
+
+  :param ent1:          Entity from which position and sequence are extracted
+                        to run MMalign.
+  :param ent2:          Entity from which position and sequence are extracted
+                        to run TMalign, this is the reference.
+  :param fast:          Whether to apply the *fast* flag to MMAlign
+  :type chain1:         :class:`ost.mol.EntityView`
+  :type chain2:         :class:`ost.mol.EntityView`
+  :type fast:           :class:`bool`
+  :rtype:               :class:`ost.bindings.MMAlignResult`

modules/bindings/pymod/export_tmalign.cc

@@ -38,6 +38,13 @@ ost::bindings::TMAlignResult WrapTMAlignView(const ost::mol::ChainView& chain1,
   return ost::bindings::WrappedTMAlign(chain1, chain2, fast);
 }
 
+ost::bindings::MMAlignResult WrapMMAlignView(const ost::mol::EntityView& ent1,
+                                             const ost::mol::EntityView& ent2, 
+                                             bool fast) {
+
+  return ost::bindings::WrappedMMAlign(ent1, ent2, fast);
+}
+
 void export_TMAlign() {
   class_<ost::bindings::TMAlignResult>("TMAlignResult", init<Real, Real, int, const geom::Mat4&, 
                                                              const ost::seq::AlignmentHandle&>())
@@ -50,9 +57,30 @@ void export_TMAlign() {
                                return_value_policy<reference_existing_object>()))
   ;
 
+  class_<ost::bindings::MMAlignResult>("MMAlignResult", init<Real, Real, const geom::Mat4&, int,
+                                                             const ost::seq::AlignmentList&,
+                                                             const std::vector<String>&,
+                                                             const std::vector<String>&>())
+    .add_property("rmsd", make_function(&ost::bindings::MMAlignResult::GetRMSD))
+    .add_property("tm_score", make_function(&ost::bindings::MMAlignResult::GetTMScore))
+    .add_property("transform", make_function(&ost::bindings::MMAlignResult::GetTransform,
+                               return_value_policy<reference_existing_object>()))
+    .add_property("aligned_length", make_function(&ost::bindings::MMAlignResult::GetAlignedLength))
+    .add_property("alignments", make_function(&ost::bindings::MMAlignResult::GetAlignments,
+                               return_value_policy<reference_existing_object>()))
+    .add_property("ent1_mapped_chains", make_function(&ost::bindings::MMAlignResult::GetEnt1MappedChains,
+                               return_value_policy<reference_existing_object>()))
+    .add_property("ent2_mapped_chains", make_function(&ost::bindings::MMAlignResult::GetEnt2MappedChains,
+                               return_value_policy<reference_existing_object>()))
+  ;
+
+
   def("WrappedTMAlign", &WrapTMAlignPos, (arg("pos1"), arg("pos2"), arg("seq1"), arg("seq2"),
                                           arg("fast")=false, arg("rna")=false));
 
   def("WrappedTMAlign", &WrapTMAlignView, (arg("chain1"), arg("chain2"),
                                            arg("fast")=false));
+
+  def("WrappedMMAlign", &WrapMMAlignView, (arg("ent1"), arg("ent2"),
+                                           arg("fast")=false));
 }

modules/bindings/src/wrap_tmalign.hh

@@ -52,6 +52,39 @@ struct TMAlignResult {
   const ost::seq::AlignmentHandle& GetAlignment() { return alignment; }
 };
 
+struct MMAlignResult {
+
+  MMAlignResult() { }
+
+  MMAlignResult(Real rm, Real tm, const geom::Mat4& t,
+                int al, const ost::seq::AlignmentList& alns,
+                const std::vector<String>& e1c,
+                const std::vector<String>& e2c): rmsd(rm),
+                                                 tm_score(tm),
+                                                 transform(t),
+                                                 aligned_length(al),
+                                                 alignments(alns),
+                                                 ent1_mapped_chains(e1c),
+                                                 ent2_mapped_chains(e2c) { } 
+
+
+  Real rmsd;
+  Real tm_score;
+  geom::Mat4 transform;
+  int aligned_length;
+  ost::seq::AlignmentList alignments;
+  std::vector<String> ent1_mapped_chains;
+  std::vector<String> ent2_mapped_chains;
+
+  Real GetTMScore() { return tm_score; }
+  Real GetRMSD() { return rmsd; }
+  int GetAlignedLength() { return aligned_length; }
+  const geom::Mat4& GetTransform() { return transform; }
+  const ost::seq::AlignmentList& GetAlignments() { return alignments; }
+  const std::vector<String>& GetEnt1MappedChains() {return ent1_mapped_chains; }
+  const std::vector<String>& GetEnt2MappedChains() {return ent2_mapped_chains; }
+};
+
 TMAlignResult WrappedTMAlign(const geom::Vec3List& pos_one, 
                              const geom::Vec3List& pos_two, 
                              const ost::seq::SequenceHandle& seq1,
@@ -59,9 +92,21 @@ TMAlignResult WrappedTMAlign(const geom::Vec3List& pos_one,
                              bool fast = false,
                              bool rna = false);
 
+MMAlignResult WrappedMMAlign(const std::vector<geom::Vec3List>& pos_one,
+                             const std::vector<geom::Vec3List>& pos_two,
+                             const ost::seq::SequenceList& seq1,
+                             const ost::seq::SequenceList& seq2,
+                             const std::vector<bool>& rna1,
+                             const std::vector<bool>& rna2,
+                             bool fast = false);
+
 TMAlignResult WrappedTMAlign(const ost::mol::ChainView& ent1,
                              const ost::mol::ChainView& ent2,
                              bool fast = false);
+
+MMAlignResult WrappedMMAlign(const ost::mol::EntityView& ent1,
+                             const ost::mol::EntityView& ent2,
+                             bool fast = false);
 }} //ns
 
 #endif

[Gerardo Tauriello]

Should this have been "type ent1"? Same for next line...

[Studer Gabriel]

Good catch! will fix