src/jalview/datamodel/SeqCigar.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8.2)
   3  * Copyright (C) 2014 The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.datamodel;
  22
  23 import java.util.Enumeration;
  24 import java.util.Hashtable;
  25
  26 import jalview.analysis.*;
  27 import jalview.util.*;
  28
  29 public class SeqCigar extends CigarSimple
  30 {
  31   /**
  32    * start(inclusive) and end(exclusive) of subsequence on refseq
  33    */
  34   private int start, end;
  35
  36   private SequenceI refseq = null;
  37
  38   private Hashtable seqProps;
  39
  40   /**
  41    * Reference dataset sequence for the cigar string
  42    *
  43    * @return SequenceI
  44    */
  45   public SequenceI getRefSeq()
  46   {
  47     return refseq;
  48   }
  49
  50   /**
  51    *
  52    * @return int start index of cigar ops on refSeq
  53    */
  54   public int getStart()
  55   {
  56     return start;
  57   }
  58
  59   /**
  60    *
  61    * @return int end index (exclusive) of cigar ops on refSeq
  62    */
  63   public int getEnd()
  64   {
  65     return end;
  66   }
  67
  68   /**
  69    * Returns sequence as a string with cigar operations applied to it
  70    *
  71    * @return String
  72    */
  73   public String getSequenceString(char GapChar)
  74   {
  75     return (length == 0) ? "" : (String) getSequenceAndDeletions(
  76             refseq.getSequenceAsString(start, end), GapChar)[0];
  77   }
  78
  79   /**
  80    * recreates a gapped and edited version of RefSeq or null for an empty cigar
  81    * string
  82    *
  83    * @return SequenceI
  84    */
  85   public SequenceI getSeq(char GapChar)
  86   {
  87     Sequence seq;
  88     if (refseq == null || length == 0)
  89     {
  90       return null;
  91     }
  92     Object[] edit_result = getSequenceAndDeletions(
  93             refseq.getSequenceAsString(start, end), GapChar);
  94     if (edit_result == null)
  95     {
  96       throw new Error(
  97               "Implementation Error - unexpected null from getSequenceAndDeletions");
  98     }
  99     int bounds[] = (int[]) edit_result[1];
 100     seq = new Sequence(refseq.getName(), (String) edit_result[0],
 101             refseq.getStart() + start + bounds[0], refseq.getStart()
 102                     + start + ((bounds[2] == 0) ? -1 : bounds[2]));
 103     seq.setDescription(refseq.getDescription());
 104     int sstart = seq.getStart(), send = seq.getEnd();
 105     // seq.checkValidRange(); probably not needed
 106     // recover local properties if present
 107     if (seqProps != null)
 108     {
 109       // this recovers dataset sequence reference as well as local features,
 110       // names, start/end settings.
 111       SeqsetUtils.SeqCharacterUnhash(seq, seqProps);
 112     }
 113     // ensure dataset sequence is up to date from local reference
 114     seq.setDatasetSequence(refseq);
 115     seq.setStart(sstart);
 116     seq.setEnd(send);
 117     return seq;
 118   }
 119
 120   /*
 121    * We don't allow this - refseq is given at construction time only public void
 122    * setSeq(SequenceI seq) { this.seq = seq; }
 123    */
 124   /**
 125    * internal constructor - sets seq to a gapless sequence derived from seq and
 126    * prepends any 'D' operations needed to get to the first residue of seq.
 127    *
 128    * @param seq
 129    *          SequenceI
 130    * @param initialDeletion
 131    *          true to mark initial dataset sequence residues as deleted in
 132    *          subsequence
 133    * @param _s
 134    *          index of first position in seq
 135    * @param _e
 136    *          index after last position in (possibly gapped) seq
 137    * @return true if gaps are present in seq
 138    */
 139   private boolean _setSeq(SequenceI seq, boolean initialDeletion, int _s,
 140           int _e)
 141   {
 142     boolean hasgaps = false;
 143     if (seq == null)
 144     {
 145       throw new Error("Implementation Error - _setSeq(null,...)");
 146     }
 147     if (_s < 0)
 148     {
 149       throw new Error("Implementation Error: _s=" + _s);
 150     }
 151     String seq_string = seq.getSequenceAsString();
 152     if (_e == 0 || _e < _s || _e > seq_string.length())
 153     {
 154       _e = seq_string.length();
 155     }
 156     // resolve start and end positions relative to ungapped reference sequence
 157     start = seq.findPosition(_s) - seq.getStart();
 158     end = seq.findPosition(_e) - seq.getStart();
 159     int l_ungapped = end - start;
 160     // Find correct sequence to reference and correct start and end - if
 161     // necessary
 162     SequenceI ds = seq.getDatasetSequence();
 163     if (ds == null)
 164     {
 165       // make a new dataset sequence
 166       String ungapped = AlignSeq.extractGaps(
 167               jalview.util.Comparison.GapChars, new String(seq_string));
 168       l_ungapped = ungapped.length();
 169       // check that we haven't just duplicated an ungapped sequence.
 170       if (l_ungapped == seq.getLength())
 171       {
 172         ds = seq;
 173       }
 174       else
 175       {
 176         ds = new Sequence(seq.getName(), ungapped, seq.getStart(),
 177                 seq.getStart() + ungapped.length() - 1);
 178         // JBPNote: this would be consistent but may not be useful
 179         // seq.setDatasetSequence(ds);
 180       }
 181     }
 182     // add in offset between seq and the dataset sequence
 183     if (ds.getStart() < seq.getStart())
 184     {
 185       int offset = seq.getStart() - ds.getStart();
 186       if (initialDeletion)
 187       {
 188         // absolute cigar string
 189         addDeleted(_s + offset);
 190         start = 0;
 191         end += offset;
 192       }
 193       else
 194       {
 195         // normal behaviour - just mark start and end subsequence
 196         start += offset;
 197         end += offset;
 198
 199       }
 200
 201     }
 202
 203     // any gaps to process ?
 204     if (l_ungapped != (_e - _s))
 205     {
 206       hasgaps = true;
 207     }
 208
 209     refseq = ds;
 210     // copy over local properties for the sequence instance of the refseq
 211     seqProps = SeqsetUtils.SeqCharacterHash(seq);
 212     // Check offsets
 213     if (end > ds.getLength())
 214     {
 215       throw new Error(
 216               "SeqCigar: Possible implementation error: sequence is longer than dataset sequence");
 217       // end = ds.getLength();
 218     }
 219
 220     return hasgaps;
 221   }
 222
 223   /**
 224    * directly initialise a cigar object with a sequence of range, operation
 225    * pairs and a sequence to apply it to. operation and range should be relative
 226    * to the seq.getStart()'th residue of the dataset seq resolved from seq.
 227    *
 228    * @param seq
 229    *          SequenceI
 230    * @param operation
 231    *          char[]
 232    * @param range
 233    *          int[]
 234    */
 235   public SeqCigar(SequenceI seq, char operation[], int range[])
 236   {
 237     super();
 238     if (seq == null)
 239     {
 240       throw new Error("Implementation Bug. Null seq !");
 241     }
 242     if (operation.length != range.length)
 243     {
 244       throw new Error(
 245               "Implementation Bug. Cigar Operation list!= range list");
 246     }
 247
 248     if (operation != null)
 249     {
 250       this.operation = new char[operation.length + _inc_length];
 251       this.range = new int[operation.length + _inc_length];
 252
 253       if (_setSeq(seq, false, 0, 0))
 254       {
 255         throw new Error(
 256                 "NOT YET Implemented: Constructing a Cigar object from a cigar string and a gapped sequence.");
 257       }
 258       for (int i = this.length, j = 0; j < operation.length; i++, j++)
 259       {
 260         char op = operation[j];
 261         if (op != M && op != I && op != D)
 262         {
 263           throw new Error("Implementation Bug. Cigar Operation '" + j
 264                   + "' '" + op + "' not one of '" + M + "', '" + I
 265                   + "', or '" + D + "'.");
 266         }
 267         this.operation[i] = op;
 268         this.range[i] = range[j];
 269       }
 270       this.length += operation.length;
 271     }
 272     else
 273     {
 274       this.operation = null;
 275       this.range = null;
 276       this.length = 0;
 277       if (_setSeq(seq, false, 0, 0))
 278       {
 279         throw new Error(
 280                 "NOT YET Implemented: Constructing a Cigar object from a cigar string and a gapped sequence.");
 281       }
 282     }
 283   }
 284
 285   /**
 286    * add range matched residues to cigar string
 287    *
 288    * @param range
 289    *          int
 290    */
 291   public void addMatch(int range)
 292   {
 293     this.addOperation(M, range);
 294   }
 295
 296   /**
 297    * Adds insertion and match operations based on seq to the cigar up to the
 298    * endpos column of seq.
 299    *
 300    * @param cigar
 301    *          CigarBase
 302    * @param seq
 303    *          SequenceI
 304    * @param startpos
 305    *          int
 306    * @param endpos
 307    *          int
 308    * @param initialDeletions
 309    *          if true then initial deletions will be added from start of seq to
 310    *          startpos
 311    */
 312   protected static void addSequenceOps(CigarBase cigar, SequenceI seq,
 313           int startpos, int endpos, boolean initialDeletions)
 314   {
 315     char op = '\0';
 316     int range = 0;
 317     int p = 0, res = seq.getLength();
 318
 319     if (!initialDeletions)
 320     {
 321       p = startpos;
 322     }
 323
 324     while (p <= endpos)
 325     {
 326       boolean isGap = (p < res) ? jalview.util.Comparison.isGap(seq
 327               .getCharAt(p)) : true;
 328       if ((startpos <= p) && (p <= endpos))
 329       {
 330         if (isGap)
 331         {
 332           if (range > 0 && op != I)
 333           {
 334             cigar.addOperation(op, range);
 335             range = 0;
 336           }
 337           op = I;
 338           range++;
 339         }
 340         else
 341         {
 342           if (range > 0 && op != M)
 343           {
 344             cigar.addOperation(op, range);
 345             range = 0;
 346           }
 347           op = M;
 348           range++;
 349         }
 350       }
 351       else
 352       {
 353         if (!isGap)
 354         {
 355           if (range > 0 && op != D)
 356           {
 357             cigar.addOperation(op, range);
 358             range = 0;
 359           }
 360           op = D;
 361           range++;
 362         }
 363         else
 364         {
 365           // do nothing - insertions are not made in flanking regions
 366         }
 367       }
 368       p++;
 369     }
 370     if (range > 0)
 371     {
 372       cigar.addOperation(op, range);
 373     }
 374   }
 375
 376   /**
 377    * create a cigar string for given sequence
 378    *
 379    * @param seq
 380    *          SequenceI
 381    */
 382   public SeqCigar(SequenceI seq)
 383   {
 384     super();
 385     if (seq == null)
 386     {
 387       throw new Error("Implementation error for new Cigar(SequenceI)");
 388     }
 389     _setSeq(seq, false, 0, 0);
 390     // there is still work to do
 391     addSequenceOps(this, seq, 0, seq.getLength() - 1, false);
 392   }
 393
 394   /**
 395    * Create Cigar from a range of gaps and residues on a sequence object
 396    *
 397    * @param seq
 398    *          SequenceI
 399    * @param start
 400    *          int - first column in range
 401    * @param end
 402    *          int - last column in range
 403    */
 404   public SeqCigar(SequenceI seq, int start, int end)
 405   {
 406     super();
 407     if (seq == null)
 408     {
 409       throw new Error("Implementation error for new Cigar(SequenceI)");
 410     }
 411     _setSeq(seq, false, start, end + 1);
 412     // there is still work to do
 413     addSequenceOps(this, seq, start, end, false);
 414   }
 415
 416   /**
 417    * Create a cigar object from a cigar string like '[<I|D|M><range>]+' Will
 418    * fail if the given seq already contains gaps (JBPNote: future implementation
 419    * will fix)
 420    *
 421    * @param seq
 422    *          SequenceI object resolvable to a dataset sequence
 423    * @param cigarString
 424    *          String
 425    * @return Cigar
 426    */
 427   public static SeqCigar parseCigar(SequenceI seq, String cigarString)
 428           throws Exception
 429   {
 430     Object[] opsandrange = parseCigarString(cigarString);
 431     return new SeqCigar(seq, (char[]) opsandrange[0],
 432             (int[]) opsandrange[1]);
 433   }
 434
 435   /**
 436    * create an alignment from the given array of cigar sequences and gap
 437    * character, and marking the given segments as visible in the given
 438    * columselection.
 439    *
 440    * @param alseqs
 441    * @param gapCharacter
 442    * @param colsel
 443    *          - columnSelection where hidden regions are marked
 444    * @param segments
 445    *          - visible regions of alignment
 446    * @return SequenceI[]
 447    */
 448   public static SequenceI[] createAlignmentSequences(SeqCigar[] alseqs,
 449           char gapCharacter, ColumnSelection colsel, int[] segments)
 450   {
 451     SequenceI[] seqs = new SequenceI[alseqs.length];
 452     StringBuffer[] g_seqs = new StringBuffer[alseqs.length];
 453     String[] alseqs_string = new String[alseqs.length];
 454     Object[] gs_regions = new Object[alseqs.length];
 455     for (int i = 0; i < alseqs.length; i++)
 456     {
 457       alseqs_string[i] = alseqs[i].getRefSeq().getSequenceAsString(
 458               alseqs[i].start, alseqs[i].end);
 459       gs_regions[i] = alseqs[i].getSequenceAndDeletions(alseqs_string[i],
 460               gapCharacter); // gapped sequence, {start, start col, end.
 461       // endcol}, hidden regions {{start, end, col}})
 462       if (gs_regions[i] == null)
 463       {
 464         throw new Error("Implementation error: " + i
 465                 + "'th sequence Cigar has no operations.");
 466       }
 467       g_seqs[i] = new StringBuffer((String) ((Object[]) gs_regions[i])[0]); // the
 468       // visible
 469       // gapped
 470       // sequence
 471     }
 472     // Now account for insertions. (well - deletions)
 473     // this is complicated because we must keep track of shifted positions in
 474     // each sequence
 475     ShiftList shifts = new ShiftList();
 476     for (int i = 0; i < alseqs.length; i++)
 477     {
 478       Object[] gs_region = ((Object[]) ((Object[]) gs_regions[i])[2]);
 479       if (gs_region != null)
 480
 481       {
 482         for (int hr = 0; hr < gs_region.length; hr++)
 483         {
 484           int[] region = (int[]) gs_region[hr];
 485           char[] insert = new char[region[1] - region[0] + 1];
 486           for (int s = 0; s < insert.length; s++)
 487           {
 488             insert[s] = gapCharacter;
 489           }
 490           int inspos = shifts.shift(region[2]); // resolve insertion position in
 491           // current alignment frame of
 492           // reference
 493           for (int s = 0; s < alseqs.length; s++)
 494           {
 495             if (s != i)
 496             {
 497               if (g_seqs[s].length() <= inspos)
 498               {
 499                 // prefix insertion with more gaps.
 500                 for (int l = inspos - g_seqs[s].length(); l > 0; l--)
 501                 {
 502                   g_seqs[s].append(gapCharacter); // to debug - use a diffferent
 503                   // gap character here
 504                 }
 505               }
 506               g_seqs[s].insert(inspos, insert);
 507             }
 508             else
 509             {
 510               g_seqs[s].insert(inspos,
 511                       alseqs_string[i].substring(region[0], region[1] + 1));
 512             }
 513           }
 514           shifts.addShift(region[2], insert.length); // update shift in
 515           // alignment frame of
 516           // reference
 517           if (segments == null)
 518           {
 519             // add a hidden column for this deletion
 520             colsel.hideColumns(inspos, inspos + insert.length - 1);
 521           }
 522         }
 523       }
 524     }
 525     for (int i = 0; i < alseqs.length; i++)
 526     {
 527       int[] bounds = ((int[]) ((Object[]) gs_regions[i])[1]);
 528       SequenceI ref = alseqs[i].getRefSeq();
 529       seqs[i] = new Sequence(ref.getName(), g_seqs[i].toString(),
 530               ref.getStart() + alseqs[i].start + bounds[0], ref.getStart()
 531                       + alseqs[i].start + (bounds[2] == 0 ? -1 : bounds[2]));
 532       seqs[i].setDatasetSequence(ref);
 533       seqs[i].setDescription(ref.getDescription());
 534     }
 535     if (segments != null)
 536     {
 537       for (int i = 0; i < segments.length; i += 3)
 538       {
 539         // int start=shifts.shift(segments[i]-1)+1;
 540         // int end=shifts.shift(segments[i]+segments[i+1]-1)-1;
 541         colsel.hideColumns(segments[i + 1], segments[i + 1]
 542                 + segments[i + 2] - 1);
 543       }
 544     }
 545     return seqs;
 546   }
 547
 548   /**
 549    * non rigorous testing
 550    */
 551   /**
 552    *
 553    * @param seq
 554    *          Sequence
 555    * @param ex_cs_gapped
 556    *          String
 557    * @return String
 558    */
 559   public static String testCigar_string(Sequence seq, String ex_cs_gapped)
 560   {
 561     SeqCigar c_sgapped = new SeqCigar(seq);
 562     String cs_gapped = c_sgapped.getCigarstring();
 563     if (!cs_gapped.equals(ex_cs_gapped))
 564     {
 565       System.err.println("Failed getCigarstring: incorect string '"
 566               + cs_gapped + "' != " + ex_cs_gapped);
 567     }
 568     return cs_gapped;
 569   }
 570
 571   public static boolean testSeqRecovery(SeqCigar gen_sgapped,
 572           SequenceI s_gapped)
 573   {
 574     // this is non-rigorous - start and end recovery is not tested.
 575     SequenceI gen_sgapped_s = gen_sgapped.getSeq('-');
 576     if (!gen_sgapped_s.getSequence().equals(s_gapped.getSequence()))
 577     {
 578       System.err.println("Couldn't reconstruct sequence.\n"
 579               + gen_sgapped_s.getSequenceAsString() + "\n"
 580               + s_gapped.getSequenceAsString());
 581       return false;
 582     }
 583     return true;
 584   }
 585
 586   public static void main(String argv[]) throws Exception
 587   {
 588     String o_seq;
 589     Sequence s = new Sequence("MySeq",
 590             o_seq = "asdfktryasdtqwrtsaslldddptyipqqwaslchvhttt", 39, 80);
 591     String orig_gapped;
 592     Sequence s_gapped = new Sequence(
 593             "MySeq",
 594             orig_gapped = "----asdf------ktryas---dtqwrtsasll----dddptyipqqwa----slchvhttt",
 595             39, 80);
 596     String ex_cs_gapped = "4I4M6I6M3I11M4I12M4I9M";
 597     s_gapped.setDatasetSequence(s);
 598     String sub_gapped_s;
 599     Sequence s_subsequence_gapped = new Sequence(
 600             "MySeq",
 601             sub_gapped_s = "------ktryas---dtqwrtsasll----dddptyipqqwa----slchvh",
 602             43, 77);
 603
 604     s_subsequence_gapped.setDatasetSequence(s);
 605     SeqCigar c_null = new SeqCigar(s);
 606     String cs_null = c_null.getCigarstring();
 607     if (!cs_null.equals("42M"))
 608     {
 609       System.err
 610               .println("Failed to recover ungapped sequence cigar operations:"
 611                       + ((cs_null == "") ? "empty string" : cs_null));
 612     }
 613     testCigar_string(s_gapped, ex_cs_gapped);
 614     SeqCigar gen_sgapped = SeqCigar.parseCigar(s, ex_cs_gapped);
 615     if (!gen_sgapped.getCigarstring().equals(ex_cs_gapped))
 616     {
 617       System.err.println("Failed parseCigar(" + ex_cs_gapped
 618               + ")->getCigarString()->'" + gen_sgapped.getCigarstring()
 619               + "'");
 620     }
 621     testSeqRecovery(gen_sgapped, s_gapped);
 622     // Test dataset resolution
 623     SeqCigar sub_gapped = new SeqCigar(s_subsequence_gapped);
 624     if (!testSeqRecovery(sub_gapped, s_subsequence_gapped))
 625     {
 626       System.err
 627               .println("Failed recovery for subsequence of dataset sequence");
 628     }
 629     // width functions
 630     if (sub_gapped.getWidth() != sub_gapped_s.length())
 631     {
 632       System.err.println("Failed getWidth()");
 633     }
 634
 635     sub_gapped.getFullWidth();
 636     if (sub_gapped.hasDeletedRegions())
 637     {
 638       System.err.println("hasDeletedRegions is incorrect.");
 639     }
 640     // Test start-end region SeqCigar
 641     SeqCigar sub_se_gp = new SeqCigar(s_subsequence_gapped, 8, 48);
 642     if (sub_se_gp.getWidth() != 41)
 643     {
 644       System.err
 645               .println("SeqCigar(seq, start, end) not properly clipped alignsequence.");
 646     }
 647     System.out.println("Original sequence align:\n" + sub_gapped_s
 648             + "\nReconstructed window from 8 to 48\n" + "XXXXXXXX"
 649             + sub_se_gp.getSequenceString('-') + "..." + "\nCigar String:"
 650             + sub_se_gp.getCigarstring() + "\n");
 651     SequenceI ssgp = sub_se_gp.getSeq('-');
 652     System.out.println("\t " + ssgp.getSequenceAsString());
 653     for (int r = 0; r < 10; r++)
 654     {
 655       sub_se_gp = new SeqCigar(s_subsequence_gapped, 8, 48);
 656       int sl = sub_se_gp.getWidth();
 657       int st = sl - 1 - r;
 658       for (int rs = 0; rs < 10; rs++)
 659       {
 660         int e = st + rs;
 661         sub_se_gp.deleteRange(st, e);
 662         String ssgapedseq = sub_se_gp.getSeq('-').getSequenceAsString();
 663         System.out.println(st + "," + e + "\t:" + ssgapedseq);
 664         st -= 3;
 665       }
 666     }
 667     {
 668       SeqCigar[] set = new SeqCigar[]
 669       { new SeqCigar(s), new SeqCigar(s_subsequence_gapped, 8, 48),
 670           new SeqCigar(s_gapped) };
 671       Alignment al = new Alignment(set);
 672       for (int i = 0; i < al.getHeight(); i++)
 673       {
 674         System.out.println("" + al.getSequenceAt(i).getName() + "\t"
 675                 + al.getSequenceAt(i).getStart() + "\t"
 676                 + al.getSequenceAt(i).getEnd() + "\t"
 677                 + al.getSequenceAt(i).getSequenceAsString());
 678       }
 679     }
 680     {
 681       System.out.println("Gapped.");
 682       SeqCigar[] set = new SeqCigar[]
 683       { new SeqCigar(s), new SeqCigar(s_subsequence_gapped, 8, 48),
 684           new SeqCigar(s_gapped) };
 685       set[0].deleteRange(20, 25);
 686       Alignment al = new Alignment(set);
 687       for (int i = 0; i < al.getHeight(); i++)
 688       {
 689         System.out.println("" + al.getSequenceAt(i).getName() + "\t"
 690                 + al.getSequenceAt(i).getStart() + "\t"
 691                 + al.getSequenceAt(i).getEnd() + "\t"
 692                 + al.getSequenceAt(i).getSequenceAsString());
 693       }
 694     }
 695     // if (!ssgapedseq.equals("ryas---dtqqwa----slchvh"))
 696     // System.err.println("Subseqgaped\n------ktryas---dtqwrtsasll----dddptyipqqwa----slchvhryas---dtqwrtsasll--qwa----slchvh\n"+ssgapedseq+"\n"+sub_se_gp.getCigarstring());
 697   }
 698
 699   /**
 700    * references to entities that this sequence cigar is associated with.
 701    */
 702   private Hashtable selGroups = null;
 703
 704   public void setGroupMembership(Object group)
 705   {
 706     if (selGroups == null)
 707     {
 708       selGroups = new Hashtable();
 709     }
 710     selGroups.put(group, new int[0]);
 711   }
 712
 713   /**
 714    * Test for and if present remove association to group.
 715    *
 716    * @param group
 717    * @return true if group was associated and it was removed
 718    */
 719   public boolean removeGroupMembership(Object group)
 720   {
 721     if (selGroups != null && selGroups.containsKey(group))
 722     {
 723       selGroups.remove(group);
 724       return true;
 725     }
 726     return false;
 727   }
 728
 729   /**
 730    * forget all associations for this sequence.
 731    */
 732   public void clearMemberships()
 733   {
 734     if (selGroups != null)
 735     {
 736       selGroups.clear();
 737     }
 738     selGroups = null;
 739   }
 740
 741   /**
 742    *
 743    * @return null or array of all associated entities
 744    */
 745   public Object[] getAllMemberships()
 746   {
 747     if (selGroups == null)
 748     {
 749       return null;
 750     }
 751     Object[] mmbs = new Object[selGroups.size()];
 752     Enumeration en = selGroups.keys();
 753     for (int i = 0; en.hasMoreElements(); i++)
 754     {
 755       mmbs[i] = en.nextElement();
 756     }
 757     return mmbs;
 758   }
 759
 760   /**
 761    * Test for group membership
 762    *
 763    * @param sgr
 764    *          - a selection group or some other object that may be associated
 765    *          with seqCigar
 766    * @return true if sgr is associated with this seqCigar
 767    */
 768   public boolean isMemberOf(Object sgr)
 769   {
 770     return (selGroups != null) && selGroups.get(sgr) != null;
 771   }
 772 }