2 * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
3 * Copyright (C) 2011 J Procter, AM Waterhouse, J Engelhardt, LM Lui, G Barton, M Clamp, S Searle
5 * This file is part of Jalview.
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 of the License, or (at your option) any later version.
11 * Jalview is distributed in the hope that it will be useful, but
12 * WITHOUT ANY WARRANTY; without even the implied warranty
13 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
14 * PURPOSE. See the GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License along with Jalview. If not, see <http://www.gnu.org/licenses/>.
18 package jalview.viewmodel;
20 import jalview.analysis.Conservation;
21 import jalview.api.AlignCalcManagerI;
22 import jalview.api.AlignViewportI;
23 import jalview.api.AlignmentViewPanel;
24 import jalview.datamodel.AlignmentAnnotation;
25 import jalview.datamodel.AlignmentI;
26 import jalview.datamodel.AlignmentView;
27 import jalview.datamodel.Annotation;
28 import jalview.datamodel.ColumnSelection;
29 import jalview.datamodel.Sequence;
30 import jalview.datamodel.SequenceGroup;
31 import jalview.datamodel.SequenceI;
32 import jalview.schemes.ClustalxColourScheme;
33 import jalview.schemes.ColourSchemeI;
34 import jalview.schemes.ResidueProperties;
35 import jalview.workers.AlignCalcManager;
36 import jalview.workers.ConsensusThread;
37 import jalview.workers.ConservationThread;
38 import jalview.workers.StrucConsensusThread;
40 import java.util.Hashtable;
41 import java.util.Vector;
44 * base class holding visualization and analysis attributes and common logic for
45 * an active alignment view displayed in the GUI
50 public abstract class AlignmentViewport implements AlignViewportI
53 * alignment displayed in the viewport. Please use get/setter
55 protected AlignmentI alignment;
57 protected String sequenceSetID;
60 * probably unused indicator that view is of a dataset rather than an
63 protected boolean isDataset = false;
65 private Hashtable hiddenRepSequences;
67 protected ColumnSelection colSel = new ColumnSelection();
69 public boolean autoCalculateConsensus = true;
71 protected boolean autoCalculateStrucConsensus = true;
73 protected boolean ignoreGapsInConsensusCalculation = false;
75 protected ColourSchemeI globalColourScheme = null;
78 public void setGlobalColourScheme(ColourSchemeI cs)
80 globalColourScheme = cs;
84 public ColourSchemeI getGlobalColourScheme()
86 return globalColourScheme;
89 protected AlignmentAnnotation consensus;
91 protected AlignmentAnnotation strucConsensus;
93 protected AlignmentAnnotation conservation;
95 protected AlignmentAnnotation quality;
97 protected AlignmentAnnotation[] groupConsensus;
99 protected AlignmentAnnotation[] groupConservation;
102 * results of alignment consensus analysis for visible portion of view
104 protected Hashtable[] hconsensus = null;
107 * results of secondary structure base pair consensus for visible portion of
110 protected Hashtable[] hStrucConsensus = null;
113 * percentage gaps allowed in a column before all amino acid properties should
114 * be considered unconserved
116 int ConsPercGaps = 25; // JBPNote : This should be a scalable property!
119 public int getConsPercGaps()
125 public void setSequenceConsensusHash(Hashtable[] hconsensus)
127 this.hconsensus = hconsensus;
132 public Hashtable[] getSequenceConsensusHash()
138 public Hashtable[] getRnaStructureConsensusHash()
140 return hStrucConsensus;
144 public void setRnaStructureConsensusHash(Hashtable[] hStrucConsensus)
146 this.hStrucConsensus = hStrucConsensus;
151 public AlignmentAnnotation getAlignmentQualityAnnot()
157 public AlignmentAnnotation getAlignmentConservationAnnotation()
163 public AlignmentAnnotation getAlignmentConsensusAnnotation()
169 public AlignmentAnnotation getAlignmentStrucConsensusAnnotation()
171 return strucConsensus;
174 protected AlignCalcManagerI calculator = new AlignCalcManager();
177 * trigger update of conservation annotation
179 public void updateConservation(final AlignmentViewPanel ap)
181 // see note in mantis : issue number 8585
182 if (alignment.isNucleotide() || conservation == null
183 || !autoCalculateConsensus)
188 .startRegisteredWorkersOfClass(jalview.workers.ConservationThread.class))
190 calculator.registerWorker(new jalview.workers.ConservationThread(
196 * trigger update of consensus annotation
198 public void updateConsensus(final AlignmentViewPanel ap)
200 // see note in mantis : issue number 8585
201 if (consensus == null || !autoCalculateConsensus)
205 if (!calculator.startRegisteredWorkersOfClass(ConsensusThread.class))
207 calculator.registerWorker(new ConsensusThread(this, ap));
211 // --------START Structure Conservation
212 public void updateStrucConsensus(final AlignmentViewPanel ap)
214 if (autoCalculateStrucConsensus && strucConsensus == null
215 && alignment.isNucleotide() && alignment.hasRNAStructure())
220 // see note in mantis : issue number 8585
221 if (strucConsensus == null || !autoCalculateStrucConsensus)
226 .startRegisteredWorkersOfClass(StrucConsensusThread.class))
228 calculator.registerWorker(new StrucConsensusThread(this, ap));
232 public boolean isCalcInProgress()
234 return calculator.isWorking();
238 public boolean isCalculationInProgress(
239 AlignmentAnnotation alignmentAnnotation)
241 if (!alignmentAnnotation.autoCalculated)
243 if (calculator.workingInvolvedWith(alignmentAnnotation))
245 // System.err.println("grey out ("+alignmentAnnotation.label+")");
252 public boolean isClosed()
254 // TODO: check that this isClosed is only true after panel is closed, not
255 // before it is fully constructed.
256 return alignment == null;
260 public AlignCalcManagerI getCalcManager()
266 * should conservation rows be shown for groups
268 protected boolean showGroupConservation = false;
271 * should consensus rows be shown for groups
273 protected boolean showGroupConsensus = false;
276 * should consensus profile be rendered by default
278 protected boolean showSequenceLogo = false;
281 * should consensus profile be rendered normalised to row height
283 protected boolean normaliseSequenceLogo = false;
286 * should consensus histograms be rendered by default
288 protected boolean showConsensusHistogram = true;
291 * @return the showConsensusProfile
294 public boolean isShowSequenceLogo()
296 return showSequenceLogo;
300 * @param showSequenceLogo
303 public void setShowSequenceLogo(boolean showSequenceLogo)
305 if (showSequenceLogo != this.showSequenceLogo)
307 // TODO: decouple settings setting from calculation when refactoring
308 // annotation update method from alignframe to viewport
309 this.showSequenceLogo = showSequenceLogo;
310 calculator.updateAnnotationFor(ConsensusThread.class);
311 calculator.updateAnnotationFor(StrucConsensusThread.class);
313 this.showSequenceLogo = showSequenceLogo;
317 * @param showConsensusHistogram
318 * the showConsensusHistogram to set
320 public void setShowConsensusHistogram(boolean showConsensusHistogram)
322 this.showConsensusHistogram = showConsensusHistogram;
326 * @return the showGroupConservation
328 public boolean isShowGroupConservation()
330 return showGroupConservation;
334 * @param showGroupConservation
335 * the showGroupConservation to set
337 public void setShowGroupConservation(boolean showGroupConservation)
339 this.showGroupConservation = showGroupConservation;
343 * @return the showGroupConsensus
345 public boolean isShowGroupConsensus()
347 return showGroupConsensus;
351 * @param showGroupConsensus
352 * the showGroupConsensus to set
354 public void setShowGroupConsensus(boolean showGroupConsensus)
356 this.showGroupConsensus = showGroupConsensus;
361 * @return flag to indicate if the consensus histogram should be rendered by
365 public boolean isShowConsensusHistogram()
367 return this.showConsensusHistogram;
371 * show non-conserved residues only
373 protected boolean showUnconserved = false;
376 * when set, updateAlignment will always ensure sequences are of equal length
378 private boolean padGaps = false;
381 * when set, alignment should be reordered according to a newly opened tree
383 public boolean sortByTree = false;
385 public boolean getShowUnconserved()
387 return showUnconserved;
390 public void setShowUnconserved(boolean showunconserved)
392 showUnconserved = showunconserved;
396 * @param showNonconserved
397 * the showUnconserved to set
399 public void setShowunconserved(boolean displayNonconserved)
401 this.showUnconserved = displayNonconserved;
407 * @return null or the currently selected sequence region
409 public SequenceGroup getSelectionGroup()
411 return selectionGroup;
415 * Set the selection group for this window.
418 * - group holding references to sequences in this alignment view
421 public void setSelectionGroup(SequenceGroup sg)
426 public void setHiddenColumns(ColumnSelection colsel)
428 this.colSel = colsel;
429 if (colSel.getHiddenColumns() != null)
431 hasHiddenColumns = true;
436 public ColumnSelection getColumnSelection()
441 public void setColumnSelection(ColumnSelection colSel)
443 this.colSel = colSel;
445 public Hashtable getHiddenRepSequences()
447 return hiddenRepSequences;
449 public void setHiddenRepSequences(Hashtable hiddenRepSequences)
451 this.hiddenRepSequences = hiddenRepSequences;
453 protected boolean hasHiddenColumns = false;
455 public void updateHiddenColumns()
457 hasHiddenColumns = colSel.getHiddenColumns() != null;
460 protected boolean hasHiddenRows = false;
462 public boolean hasHiddenRows()
464 return hasHiddenRows;
467 protected SequenceGroup selectionGroup;
469 public void setSequenceSetId(String newid)
471 if (sequenceSetID != null)
474 .println("Warning - overwriting a sequenceSetId for a viewport!");
476 sequenceSetID = new String(newid);
479 public String getSequenceSetId()
481 if (sequenceSetID == null)
483 sequenceSetID = alignment.hashCode() + "";
486 return sequenceSetID;
490 * unique viewId for synchronizing state (e.g. with stored Jalview Project)
493 protected String viewId = null;
495 public String getViewId()
499 viewId = this.getSequenceSetId() + "." + this.hashCode() + "";
504 public void setIgnoreGapsConsensus(boolean b, AlignmentViewPanel ap)
506 ignoreGapsInConsensusCalculation = b;
510 if (globalColourScheme != null)
512 globalColourScheme.setThreshold(globalColourScheme.getThreshold(),
513 ignoreGapsInConsensusCalculation);
519 private long sgrouphash = -1, colselhash = -1;
522 * checks current SelectionGroup against record of last hash value, and
526 * update the record of last hash value
528 * @return true if SelectionGroup changed since last call (when b is true)
530 public boolean isSelectionGroupChanged(boolean b)
532 int hc = (selectionGroup == null || selectionGroup.getSize() == 0) ? -1
533 : selectionGroup.hashCode();
534 if (hc != -1 && hc != sgrouphash)
546 * checks current colsel against record of last hash value, and optionally
550 * update the record of last hash value
551 * @return true if colsel changed since last call (when b is true)
553 public boolean isColSelChanged(boolean b)
555 int hc = (colSel == null || colSel.size() == 0) ? -1 : colSel
557 if (hc != -1 && hc != colselhash)
569 public boolean getIgnoreGapsConsensus()
571 return ignoreGapsInConsensusCalculation;
574 // / property change stuff
576 // JBPNote Prolly only need this in the applet version.
577 private final java.beans.PropertyChangeSupport changeSupport = new java.beans.PropertyChangeSupport(
580 protected boolean showConservation = true;
582 protected boolean showQuality = true;
584 protected boolean showConsensus = true;
587 * Property change listener for changes in alignment
592 public void addPropertyChangeListener(
593 java.beans.PropertyChangeListener listener)
595 changeSupport.addPropertyChangeListener(listener);
604 public void removePropertyChangeListener(
605 java.beans.PropertyChangeListener listener)
607 changeSupport.removePropertyChangeListener(listener);
611 * Property change listener for changes in alignment
620 public void firePropertyChange(String prop, Object oldvalue,
623 changeSupport.firePropertyChange(prop, oldvalue, newvalue);
626 // common hide/show column stuff
628 public void hideSelectedColumns()
630 if (colSel.size() < 1)
635 colSel.hideSelectedColumns();
636 setSelectionGroup(null);
638 hasHiddenColumns = true;
641 public void hideColumns(int start, int end)
645 colSel.hideColumns(start);
649 colSel.hideColumns(start, end);
652 hasHiddenColumns = true;
655 public void showColumn(int col)
657 colSel.revealHiddenColumns(col);
658 if (colSel.getHiddenColumns() == null)
660 hasHiddenColumns = false;
664 public void showAllHiddenColumns()
666 colSel.revealAllHiddenColumns();
667 hasHiddenColumns = false;
670 // common hide/show seq stuff
671 public void showAllHiddenSeqs()
673 if (alignment.getHiddenSequences().getSize() > 0)
675 if (selectionGroup == null)
677 selectionGroup = new SequenceGroup();
678 selectionGroup.setEndRes(alignment.getWidth() - 1);
680 Vector tmp = alignment.getHiddenSequences().showAll(
682 for (int t = 0; t < tmp.size(); t++)
684 selectionGroup.addSequence((SequenceI) tmp.elementAt(t), false);
687 hasHiddenRows = false;
688 hiddenRepSequences = null;
690 firePropertyChange("alignment", null, alignment.getSequences());
691 // used to set hasHiddenRows/hiddenRepSequences here, after the property
697 public void showSequence(int index)
699 Vector tmp = alignment.getHiddenSequences().showSequence(index,
703 if (selectionGroup == null)
705 selectionGroup = new SequenceGroup();
706 selectionGroup.setEndRes(alignment.getWidth() - 1);
709 for (int t = 0; t < tmp.size(); t++)
711 selectionGroup.addSequence((SequenceI) tmp.elementAt(t), false);
713 // JBPNote: refactor: only update flag if we modified visiblity (used to
714 // do this regardless)
715 if (alignment.getHiddenSequences().getSize() < 1)
717 hasHiddenRows = false;
719 firePropertyChange("alignment", null, alignment.getSequences());
724 public void hideAllSelectedSeqs()
726 if (selectionGroup == null || selectionGroup.getSize() < 1)
731 SequenceI[] seqs = selectionGroup.getSequencesInOrder(alignment);
735 setSelectionGroup(null);
738 public void hideSequence(SequenceI[] seq)
742 for (int i = 0; i < seq.length; i++)
744 alignment.getHiddenSequences().hideSequence(seq[i]);
746 hasHiddenRows = true;
747 firePropertyChange("alignment", null, alignment.getSequences());
751 public void hideRepSequences(SequenceI repSequence, SequenceGroup sg)
753 int sSize = sg.getSize();
759 if (hiddenRepSequences == null)
761 hiddenRepSequences = new Hashtable();
764 hiddenRepSequences.put(repSequence, sg);
766 // Hide all sequences except the repSequence
767 SequenceI[] seqs = new SequenceI[sSize - 1];
769 for (int i = 0; i < sSize; i++)
771 if (sg.getSequenceAt(i) != repSequence)
773 if (index == sSize - 1)
778 seqs[index++] = sg.getSequenceAt(i);
781 sg.setSeqrep(repSequence); // note: not done in 2.7applet
782 sg.setHidereps(true); // note: not done in 2.7applet
787 public boolean isHiddenRepSequence(SequenceI seq)
789 return hiddenRepSequences != null
790 && hiddenRepSequences.containsKey(seq);
793 public SequenceGroup getRepresentedSequences(SequenceI seq)
795 return (SequenceGroup) (hiddenRepSequences == null ? null
796 : hiddenRepSequences.get(seq));
799 public int adjustForHiddenSeqs(int alignmentIndex)
801 return alignment.getHiddenSequences().adjustForHiddenSeqs(
805 // Selection manipulation
807 * broadcast selection to any interested parties
809 public abstract void sendSelection();
811 public void invertColumnSelection()
813 colSel.invertColumnSelection(0, alignment.getWidth());
817 * This method returns an array of new SequenceI objects derived from the
818 * whole alignment or just the current selection with start and end points
821 * @note if you need references to the actual SequenceI objects in the
822 * alignment or currently selected then use getSequenceSelection()
823 * @return selection as new sequenceI objects
825 public SequenceI[] getSelectionAsNewSequence()
827 SequenceI[] sequences;
828 // JBPNote: Need to test jalviewLite.getSelectedSequencesAsAlignmentFrom -
829 // this was the only caller in the applet for this method
830 // JBPNote: in applet, this method returned references to the alignment
831 // sequences, and it did not honour the presence/absence of annotation
832 // attached to the alignment (probably!)
833 if (selectionGroup == null)
835 sequences = alignment.getSequencesArray();
836 AlignmentAnnotation[] annots = alignment.getAlignmentAnnotation();
837 for (int i = 0; i < sequences.length; i++)
839 sequences[i] = new Sequence(sequences[i], annots); // construct new
847 sequences = selectionGroup.getSelectionAsNewSequences(alignment);
854 * get the currently selected sequence objects or all the sequences in the
857 * @return array of references to sequence objects
859 public SequenceI[] getSequenceSelection()
861 SequenceI[] sequences = null;
862 if (selectionGroup != null)
864 sequences = selectionGroup.getSequencesInOrder(alignment);
866 if (sequences == null)
868 sequences = alignment.getSequencesArray();
874 * This method returns the visible alignment as text, as seen on the GUI, ie
875 * if columns are hidden they will not be returned in the result. Use this for
876 * calculating trees, PCA, redundancy etc on views which contain hidden
881 public jalview.datamodel.CigarArray getViewAsCigars(
882 boolean selectedRegionOnly)
884 return new jalview.datamodel.CigarArray(alignment,
885 (hasHiddenColumns ? colSel : null),
886 (selectedRegionOnly ? selectionGroup : null));
890 * return a compact representation of the current alignment selection to pass
891 * to an analysis function
893 * @param selectedOnly
894 * boolean true to just return the selected view
895 * @return AlignmentView
897 public jalview.datamodel.AlignmentView getAlignmentView(
898 boolean selectedOnly)
900 return getAlignmentView(selectedOnly, false);
904 * return a compact representation of the current alignment selection to pass
905 * to an analysis function
907 * @param selectedOnly
908 * boolean true to just return the selected view
910 * boolean true to annotate the alignment view with groups on the
911 * alignment (and intersecting with selected region if selectedOnly
913 * @return AlignmentView
915 public jalview.datamodel.AlignmentView getAlignmentView(
916 boolean selectedOnly, boolean markGroups)
918 return new AlignmentView(alignment, colSel, selectionGroup,
919 hasHiddenColumns, selectedOnly, markGroups);
923 * This method returns the visible alignment as text, as seen on the GUI, ie
924 * if columns are hidden they will not be returned in the result. Use this for
925 * calculating trees, PCA, redundancy etc on views which contain hidden
930 public String[] getViewAsString(boolean selectedRegionOnly)
932 String[] selection = null;
933 SequenceI[] seqs = null;
935 int start = 0, end = 0;
936 if (selectedRegionOnly && selectionGroup != null)
938 iSize = selectionGroup.getSize();
939 seqs = selectionGroup.getSequencesInOrder(alignment);
940 start = selectionGroup.getStartRes();
941 end = selectionGroup.getEndRes() + 1;
945 iSize = alignment.getHeight();
946 seqs = alignment.getSequencesArray();
947 end = alignment.getWidth();
950 selection = new String[iSize];
951 if (hasHiddenColumns)
953 selection = colSel.getVisibleSequenceStrings(start, end, seqs);
957 for (i = 0; i < iSize; i++)
959 selection[i] = seqs[i].getSequenceAsString(start, end);
967 * return visible region boundaries within given column range
970 * first column (inclusive, from 0)
972 * last column (exclusive)
973 * @return int[][] range of {start,end} visible positions
975 public int[][] getVisibleRegionBoundaries(int min, int max)
977 Vector regions = new Vector();
983 if (hasHiddenColumns)
987 start = colSel.adjustForHiddenColumns(start);
990 end = colSel.getHiddenBoundaryRight(start);
1001 regions.addElement(new int[]
1004 if (hasHiddenColumns)
1006 start = colSel.adjustForHiddenColumns(end);
1007 start = colSel.getHiddenBoundaryLeft(start) + 1;
1009 } while (end < max);
1011 int[][] startEnd = new int[regions.size()][2];
1013 regions.copyInto(startEnd);
1020 * @return the padGaps
1022 public boolean isPadGaps()
1029 * the padGaps to set
1031 public void setPadGaps(boolean padGaps)
1033 this.padGaps = padGaps;
1037 * apply any post-edit constraints and trigger any calculations needed after
1038 * an edit has been performed on the alignment
1042 public void alignmentChanged(AlignmentViewPanel ap)
1046 alignment.padGaps();
1048 if (autoCalculateConsensus)
1050 updateConsensus(ap);
1052 if (hconsensus != null && autoCalculateConsensus)
1054 updateConservation(ap);
1056 if (autoCalculateStrucConsensus)
1058 updateStrucConsensus(ap);
1061 // Reset endRes of groups if beyond alignment width
1062 int alWidth = alignment.getWidth();
1063 Vector groups = alignment.getGroups();
1066 for (int i = 0; i < groups.size(); i++)
1068 SequenceGroup sg = (SequenceGroup) groups.elementAt(i);
1069 if (sg.getEndRes() > alWidth)
1071 sg.setEndRes(alWidth - 1);
1076 if (selectionGroup != null && selectionGroup.getEndRes() > alWidth)
1078 selectionGroup.setEndRes(alWidth - 1);
1081 resetAllColourSchemes();
1082 calculator.restartWorkers();
1083 // alignment.adjustSequenceAnnotations();
1088 * reset scope and do calculations for all applied colourschemes on alignment
1090 void resetAllColourSchemes()
1092 ColourSchemeI cs = globalColourScheme;
1095 cs.alignmentChanged(alignment);
1096 // TODO: fold all recalc events for clustalX into alignmentChanged
1097 if (cs instanceof ClustalxColourScheme)
1099 ((ClustalxColourScheme) cs).resetClustalX(alignment.getSequences(),
1100 alignment.getWidth());
1103 cs.setConsensus(hconsensus);
1104 if (cs.conservationApplied())
1106 cs.setConservation(Conservation.calculateConservation("All",
1107 ResidueProperties.propHash, 3, alignment.getSequences(), 0,
1108 alignment.getWidth(), false, getConsPercGaps(), false));
1112 int s, sSize = alignment.getGroups().size();
1113 for (s = 0; s < sSize; s++)
1115 SequenceGroup sg = (SequenceGroup) alignment.getGroups().elementAt(s);
1116 if (sg.cs != null && sg.cs instanceof ClustalxColourScheme)
1118 ((ClustalxColourScheme) sg.cs).resetClustalX(sg
1119 .getSequences(hiddenRepSequences), sg.getWidth());
1121 sg.recalcConservation();
1125 protected void initAutoAnnotation()
1127 // TODO: add menu option action that nulls or creates consensus object
1128 // depending on if the user wants to see the annotation or not in a
1129 // specific alignment
1131 if (hconsensus == null && !isDataset)
1133 if (!alignment.isNucleotide())
1135 if (showConservation)
1137 if (conservation == null)
1139 conservation = new AlignmentAnnotation("Conservation",
1140 "Conservation of total alignment less than "
1141 + getConsPercGaps() + "% gaps",
1142 new Annotation[1], 0f, 11f,
1143 AlignmentAnnotation.BAR_GRAPH);
1144 conservation.hasText = true;
1145 conservation.autoCalculated = true;
1146 alignment.addAnnotation(conservation);
1151 if (quality == null)
1153 quality = new AlignmentAnnotation("Quality",
1154 "Alignment Quality based on Blosum62 scores",
1155 new Annotation[1], 0f, 11f,
1156 AlignmentAnnotation.BAR_GRAPH);
1157 quality.hasText = true;
1158 quality.autoCalculated = true;
1159 alignment.addAnnotation(quality);
1165 if (alignment.hasRNAStructure())
1167 strucConsensus = new AlignmentAnnotation("StrucConsensus", "PID",
1168 new Annotation[1], 0f, 100f,
1169 AlignmentAnnotation.BAR_GRAPH);
1170 strucConsensus.hasText = true;
1171 strucConsensus.autoCalculated = true;
1175 consensus = new AlignmentAnnotation("Consensus", "PID",
1176 new Annotation[1], 0f, 100f, AlignmentAnnotation.BAR_GRAPH);
1177 consensus.hasText = true;
1178 consensus.autoCalculated = true;
1182 alignment.addAnnotation(consensus);
1183 if (strucConsensus != null)
1185 alignment.addAnnotation(strucConsensus);