Package com.biomatters.geneious.publicapi.plugin

Class SequenceSelectionWithDocuments

    • Field Detail

      • TRIMMING_EXTRACTION_STRATEGY

        public static final SequenceSelectionWithDocuments.ExtractionStrategy TRIMMING_EXTRACTION_STRATEGY
        An ExtractionStrategy that does what SequenceSelectionWithDocuments.DefaultExtractionStrategy does, but additionally performs trimming on the sequences, such that any leading or trailing trim annotations are respected and these portions of the sequence are left out of the extraction.
        Since:
        API 4.600 (Geneious 6.0.0)

    • Constructor Detail

      • SequenceSelectionWithDocuments

        public SequenceSelectionWithDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                      SequenceSelection selection,
                                      SequenceSelectionWithDocuments.ExtractionStrategy extractionStrategy)
                               throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Constructs an SequenceSelectionWithDocuments for the given documents and given SelectionSelection on those documents.
        Parameters:
        documents - the List of Documents for which this SequenceSelectionWithDocuments's SequenceSelection is defined on. Must not be null, and must not contain nulls, but can be an empty list.
        selection - the SequenceSelection to group together with its List of Documents. Must not be null.
        extractionStrategy - the ExtractionStrategy which determines how this SequenceSelectionWithDocuments will return sequences when getSequences() is called. At present, there are two choices: DEFAULT_EXTRACTION_STRATEGY and TRIMMING_EXTRACTION_STRATEGY.
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if there was an error loading the PluginDocument from one of documents
        Since:
        API 4.600 (Geneious 6.0.0)

      • SequenceSelectionWithDocuments

        public SequenceSelectionWithDocuments​(java.util.List<AnnotatedPluginDocument> documents)
                               throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Invokes SequenceSelectionWithDocuments(java.util.List, ExtractionStrategy) with DEFAULT_EXTRACTION_STRATEGY.
        Parameters:
        documents - the List of Documents for which this SequenceSelectionWithDocuments's SequenceSelection is defined on. Must not be null, but can be an empty list.
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if there was an error loading the PluginDocument from one of documents
        java.lang.IllegalArgumentException - if documents is empty, or if they're not valid to create a selection over.

      • SequenceSelectionWithDocuments

        public SequenceSelectionWithDocuments​(java.util.List<AnnotatedPluginDocument> documents,
                                      SequenceSelectionWithDocuments.ExtractionStrategy extractionStrategy)
                               throws com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Constructor which "selects all" from the given documents.
        It infers the SequenceType and SequenceSelection.SequenceDocumentType from the documents.
        If the documents contain a mixture of nucleotide and amino acid sequences, this will throw an DocumentsInvalidException. If the documents are CombinedAlignmentAndSequenceDocument this will return a selection for the sequences instead of the alignments. If there are a mixture of documents of different types (sequence vs alignment) this will throw an IllegalArgumentException.
        Parameters:
        documents - the List of Documents for which this SequenceSelectionWithDocuments's SequenceSelection is defined on. Must not be null, but can be an empty list.
        extractionStrategy - the ExtractionStrategy to use when getting sequences.
        Throws:
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if there was an error loading the PluginDocument from one of documents
        SequenceSelectionWithDocuments.DocumentsInvalidException - if there is a mixture of nucleotide and amino acid sequences
        java.lang.IllegalArgumentException - if documents is empty, or if the documents are not valid to create a selection over.
        Since:
        API 4.600 (Geneious 6.0.0)

      • SequenceSelectionWithDocuments

        public SequenceSelectionWithDocuments​(org.jdom.Element element)
                               throws XMLSerializationException,
                                      com.biomatters.geneious.publicapi.plugin.DocumentOperationException
        Construct a SequenceSelectionWithDocuments from the results of toXML()
        Parameters:
        element - an element returned from toXML()
        Throws:
        XMLSerializationException - if XML does not conform to our unpublished specification
        com.biomatters.geneious.publicapi.plugin.DocumentOperationException - if one occurred when getting a PluginDocument from one of the AnnotatedPluginDocument taken from the deserialized list.
        Since:
        API 4.40 (Geneious 5.4.0)

    • Method Detail

      • setDoRevisionNumberChecks

        public void setDoRevisionNumberChecks​(boolean doRevisionNumberChecks)
        When getSequences() is called, checks are made to make sure that the revision of the document hasn't changed and will throw a SequenceSelectionWithDocuments.SelectedDocumentsModifiedException if so. However in some cases you may want to disable this behaviour and manually handle the revision numbers.

        The associated field will not get serialized to XML.
        Parameters:
        doRevisionNumberChecks - true to throw an exception if the revision number has changed since the SequenceSelection was created when getSequences() or most other methods in this class are accessed, false otherwise
        Since:
        API 4.703 (Geneious 7.0.3)

      • getReferenceSequences

        public java.util.List<SequenceAlignmentDocument.ReferencedSequence> getReferenceSequences()
        If everything in the documents in this SequenceSelection is selected, return a list of the ReferencedSequences representing the AnnotatedPluginDocument which each sequence in the selection appears in and its index therein. If this was a partial selection, return null.
        Returns:
        referencedSequences representing the AnnotatedPluginDocument which each sequence in the selection appears in and its index therein
        Since:
        API 4.700 (Geneious 7.0.0)

      • getSequenceSelection

        public SequenceSelection getSequenceSelection()
        Returns:
        the SequenceSelection that this SequenceSelectionWithDocuments object wraps. will never be null.

      • getSequences

        public java.util.List<SequenceDocument> getSequences()
        Returns the sequences referred to by this object's SequenceSelection for its List of AnnotatedPluginDocument, as a List of SequenceDocument, applying the given ExtractionStrategy in order to extract sequences. May return 0-length sequences. The length of this list will be equal to the sum of the number of sequences in each interval

        NOTE: since API 4.600 (Geneious 6.0.0), this method's behaviour will depend on the ExtractionStrategy passed in as an argument to this class's constructor. SequenceSelectionWithDocuments serialized before this time will be deserialized with DefaultExtractionStrategy, and their behaviour will remain unchanged.
        Returns:
        the sequences referred to by this object's SequenceSelection for its List of AnnotatedPluginDocument, as a List of SequenceDocument
        See Also:
        getSequences()

      • subSelection

        public SequenceSelectionWithDocuments subSelection​(int... sequenceIndices)
        Given a set of indices specifying some of this class's SequenceSelection's intervals, determines which AnnotatedPluginDocuments are referenced by those SelectionIntervals, and groups them together into a List. A new SequenceSelection containing only the given SelectionInterval objects is created, which is defined on the new List of referenced AnnotatedPluginDocument. The List of AnnotatedPluginDocument and the SelectionInterval are wrapped together in a new SequenceSelectionWithDocuments and returned.
        Parameters:
        sequenceIndices - a list of the indices of the SequenceIntervals in this object's SequenceSelection, to create a new SelectionSelection for. This must be a subset of the ones returned by getSequenceSelection() and SequenceSelection.getIntervals()
        Returns:
        the resulting SequenceSelectionWithDocuments

      • toXML

        public org.jdom.Element toXML​(Geneious.MajorVersion majorVersion,
                              jebl.util.ProgressListener progressListener)
        Description copied from interface: XMLSerializable.OldVersionCompatible
        Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious. It is acceptable for the XML to include unnecessary tags that will be ignored by the earlier version. For example if the implementation has only extended the XML since the earlier version, then the XML returned may be identical to the XML returned for the current version.

        See XMLSerializable.toXML() for a more detailed description of what it means to serialize to XML.

        All classes that implement this method must also implement XMLSerializable.toXML() and should delegate back to this method using Geneious.getMajorVersion() and ProgressListener.EMPTY as parameters.

        Specified by:
        toXML in interface XMLSerializable.OldVersionCompatible
        Parameters:
        majorVersion - the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". This must be a version returned greater or equal to a version returned from getVersionSupport(VersionSupportType.OldestVersionSerializableTo) and must never be greater than the current version (Geneious.getMajorVersion())
        progressListener - for reporting progress and cancelling
        Returns:
        object encoded as a JDOM element

      • fromXML

        public void fromXML​(org.jdom.Element element)
             throws XMLSerializationException
        Description copied from interface: XMLSerializable
        Restore the object from the JDOM Element returned by XMLSerializable.toXML().

        This method generally should not be called directly. Instead, you should usually call XMLSerializer.classFromXML(org.jdom.Element) or XMLSerializer.classFromXML(org.jdom.Element, Class) which calls this method internally.

        It is optional to implement this method. Instead of implementing an empty constructor and implementing this method properly, the implementation may instead throw an UnsupportedOperationException and implement a constructor that takes a single Element as a parameter. This allows for cleaner code such as support for final fields in the XMLSerializable class.

        The element parameter should not be modified since it may be reused. If you need a modified version of it, take a copy with Element.clone().

        Specified by:
        fromXML in interface XMLSerializable
        Parameters:
        element - representation from a previous call to XMLSerializable.toXML()
        Throws:
        XMLSerializationException - if the Element can't be converted into this type of object