sbtabpy 1.1.1__py3-none-any.whl

sbtab/SBtab.py

@@ -0,0 +1,1714 @@
+"""
+sbtab is a table format for Systems Biology.
+
+It can store different kinds of data. The SBtabTable and SBtabDocument
+classes allow the storage, manipulation, and removal of data from the tables.
+
+See specification for further information.
+"""
+
+import datetime
+import logging
+import re
+from collections.abc import Mapping
+from pathlib import Path
+
+from . import utils
+
+# Sentinel for get_attribute(), so that default=None can be told from no default.
+_MISSING = object()
+
+
+def _attribute_pattern(attribute):
+    """
+    Return a regex matching attribute='value' in a declaration row.
+
+    The attribute name is escaped and must not be preceded by a word character,
+    so that e.g. 'Name' does not match inside "TableName='...'".
+    """
+    return r"(?<![\w])%s='([^']*)'" % re.escape(attribute)
+
+
+def _bare_column_name(column):
+    """Return a column name without its (single) leading '!'."""
+    return column[1:] if column.startswith("!") else column
+
+
+def read_csv(filepath, document_name, xlsx=False, definitions_file=None):
+    """
+    Read an sbtab file; it can be csv, but also tsv.
+
+    Parameters
+    ----------
+    filepath: str
+        Path to the file that shall be read.
+    document_name: str
+        A name for the document to be created.
+    xlsx: Bool
+        Boolean flag that indicates if the file is in xlsx format.
+
+    Returns: sbtab.SBtabDocument
+        sbtab document which is created from the given file.
+    """
+    sbtab_file = False
+
+    if xlsx:
+        try:
+            sbtab_xlsx = open(filepath, "rb")
+            sbtab_tsv = utils.xlsx_to_tsv(sbtab_xlsx, f="file")
+            sbtab_xlsx.close()
+            sbtab_doc = SBtabDocument(
+                document_name, sbtab_tsv, filepath, definitions_file
+            )
+            return sbtab_doc
+        except Exception as e:
+            raise SBtabError("The sbtab could not be generated: %s" % (str(e)))
+
+    try:
+        sbtab_file = open(filepath, "r")
+        sbtab_doc = SBtabDocument(
+            document_name, sbtab_file.read(), filepath, definitions_file
+        )
+        sbtab_file.close()
+        return sbtab_doc
+    except Exception as e:
+        if sbtab_file:
+            sbtab_file.close()
+        raise SBtabError("The sbtab could not be generated: %s" % (str(e)))
+
+
+class SBtabError(Exception):
+    """Base class for errors in the sbtab class."""
+
+    def __init__(self, *args):
+        """Initialize SBtabError with message."""
+        super().__init__(*args)
+        self.message = args[0] if args else ""
+
+    def __str__(self):
+        """Return string representation of error."""
+        return self.message
+
+
+class SBtabTable:
+    """SBtabTable (version 1.0.0 24/12/2018)."""
+
+    def __init__(self, table_string=None, filename=None):
+        """
+        Create sbtab table object from string.
+
+        Parameters
+        ----------
+        table : str
+            One sbtab string from read file.
+        filename : str
+            Filename with extension.
+        """
+        if filename:
+            self.set_filename(filename)
+        else:
+            self.filename = None
+
+        if table_string:
+            self.add_sbtab_string(table_string)
+
+        self.object_type = "table"
+
+    def _validate_extension(self, test=None):
+        """Check the extension of the file for invalid formats."""
+        valid_extensions = {".tsv", ".csv", ".xlsx"}
+        filename = test if test is not None else self.filename
+        suffix = Path(filename).suffix
+        if suffix not in valid_extensions:
+            raise SBtabError(
+                "The file extension of %s is not valid for an sbtab file." % filename
+            )
+        return True
+
+    def _singular(self):
+        """
+        Check that SBtabTable contains only one sbtab.
+
+        If more than one SBtabs are contained, an error is issued and
+        the usage of SBtabDocument is suggested.
+        """
+        header_row_count = 0
+        for row in self.table_string.split("\n"):
+            if row.startswith("!!SBtab") or row.startswith("!!ObjTables"):
+                header_row_count += 1
+
+        if header_row_count > 1:
+            raise SBtabError(
+                "There are more than one sbtab tables in this file. Please"
+                " use the SBtabDocument class instead of SBtabTable."
+            )
+
+    def _preprocess_table_string(self, table_string):
+        """
+        Preprocess the table string to fix common formatting problems.
+
+        There is so much stuff that can be made wrong with the input files.
+        This function tries to catch some of the common problems.
+        """
+        table_string = table_string.replace("\r", "")
+        table_string = table_string.replace("^M", "")
+        table_string_prep = ""
+
+        for row in table_string.split("\n"):
+            row = self._dequote(row)
+            row = row.replace("=''", "X@X")
+            while "''" in row:
+                row = row.replace("''", "'")
+            row = row.replace("X@X", "=''")
+            row.replace(
+                "%s,%s" % (self.delimiter, self.delimiter),
+                "%s%s" % (self.delimiter, self.delimiter),
+            )
+            table_string_prep += row + "\n"
+
+        return table_string_prep
+
+    def _cut_table_string(self, table_string, delimiter_test=None):
+        """
+        Cut the sbtab string into a list to harvest content.
+
+        The sbtab is initially given as one long string; cut down this
+        string into list to harvest content.
+        """
+        if delimiter_test:
+            delimiter = delimiter_test
+        else:
+            delimiter = self.delimiter
+
+        table_list = []
+        for row in table_string.split("\n"):
+            if row.replace(delimiter, "") != "" and row.replace(delimiter, "") != "[]":
+                if not row.startswith('"!') and not row.startswith("!"):
+                    if "'" in row or "{" in row or "[" in row:
+                        try:
+                            cut_row = self._handle_row(row, delimiter)
+                            table_list.append(cut_row)
+                        except Exception:
+                            print(
+                                "Row %s could not be attached due to bad syntax." % row
+                            )
+                    else:
+                        table_list.append(row.split(delimiter))
+                else:
+                    table_list.append(row.split(delimiter))
+
+        return table_list
+
+    def _handle_row(self, row, delimiter):
+        """
+        Handle rows that may contain characters causing format troubles.
+
+        Some rows may contain characters that cause format troubles:
+        quotes, commas, JSON strings, and combinations of them. This
+        function carefully handles these issues and cuts the row into
+        its correct single pieces (which are the columns).
+        """
+        # provide an anchor for the end of the row to support our regex
+        row += delimiter
+
+        # first, unify the employed quotes to '
+        row = self._dequote(row)
+
+        # then, find all quoted columns
+        if "'" in row or "{" in row or "[" in row:
+            # find beginning and start of quoted columns
+            iterators = re.finditer(r"('.*?')%s" % delimiter, row)
+            indices = [0]
+
+            for i in iterators:
+                indices.append(i.start())
+                indices.append(i.end())
+
+            # remove duplicates
+            indices_set = list(sorted(set(indices)))
+
+            # cut row at the beginning and start indices
+            items_pre = [
+                row[i : j - 1]
+                for i, j in zip(indices_set, indices_set[1:] + [len(row) + 1])
+            ]
+
+            # further cut row at the delimiter and finish off items
+            items = []
+            jsons = []
+            jlist = []
+            running_json = False
+            running_jlist = False
+
+            for item in items_pre:
+                # in the case of a comma as separator, we need to be careful
+                # with the JSONs which naturally hold commas
+                if delimiter == ",":
+                    # 1st case: we have a currently open JSON column
+                    if running_json and not item.endswith("}'"):
+                        jsons.append(item)
+                    # 2nd case: we have a JSON column start
+                    elif item.startswith("'{"):
+                        jsons.append(item)
+                        running_json = True
+                        if item.endswith("}'"):
+                            while "" in jsons:
+                                jsons.remove("")
+                            items.append(",".join(jsons))
+                            jsons = []
+                            running_json = False
+                    # 3rd case: we have a JSON column end
+                    elif running_json and item.endswith("}'"):
+                        jsons.append(item)
+                        while "" in jsons:
+                            jsons.remove("")
+                        items.append(",".join(jsons))
+                        jsons = []
+                        running_json = False
+
+                    # 1bst case: we have a currently open Jlist column
+                    elif running_jlist and not item.endswith("]'"):
+                        if item.strip() != "":
+                            jlist.append(item)
+                    # 2bnd case: we have a Jlist column start
+                    elif item.startswith("'["):
+                        jlist.append(item)
+                        running_jlist = True
+                        if item.endswith("]'"):
+                            while "" in jlist:
+                                jlist.remove("")
+                            items.append(",".join(jlist))
+                            jlist = []
+                            running_jlist = False
+                    # 3brd case: we have a Jlist column end
+                    elif running_jlist and item.endswith("]'"):
+                        jlist.append(item)
+                        while "" in jlist:
+                            jlist.remove("")
+                        items.append(",".join(jlist))
+                        jlist = []
+                        running_jlist = False
+
+                    # 4th case: we have a quoted column
+                    elif (
+                        item.startswith("'")
+                        and not item.startswith("'{")
+                        and not item.endswith("}'")
+                        and not item.startswith("'[")
+                        and not item.endswith("]'")
+                    ):
+                        items.append(item)
+
+                    # 5th case: we have a normal column
+                    elif item == "":
+                        items += [""]
+                    else:
+                        items = items + item.split(delimiter)
+                else:
+                    # for all other delimiters we are comparably easy going:
+                    if item.startswith("'"):
+                        items.append(item)
+                    else:
+                        items = items + item.split(delimiter)
+
+        # remove the last element which was added in the beginning
+        items.pop()
+
+        return items
+
+    def _initialize_table(self):
+        """Load table information and class variables."""
+        # read a potential document row
+        self.doc_row = self._get_doc_row()
+
+        # Read the header row from table
+        self.header_row = self._get_header_row()
+
+        # Read the table information from header row
+        (
+            self.table_id,
+            self.table_type,
+            self.table_name,
+            self.table_document,
+            self.table_version,
+            self.standard_concentration,
+        ) = self._get_table_information()
+
+        # Read the columns of the table
+        self.columns, self.columns_dict = self._get_columns()
+
+        # Read data rows
+        self.value_rows = self._get_rows()
+
+    def _get_doc_row(self):
+        """
+        Check if the sbtab Table holds a !!!-line to declare a belonging sbtab document.
+
+        See if the sbtab Table holds a !!!-line to declare a belonging sbtab
+        document.
+        """
+        doc_row_dq = False
+
+        for row in self.table:
+            for entry in row:
+                if str(entry).startswith("!!!"):
+                    doc_row = row
+                    doc_row_dq = self._dequote(doc_row)
+
+                    # determine if this is an sbtab or ObjTables Document
+                    if "!!!ObjTables" in doc_row_dq:
+                        self.document_format = "ObjTables"
+                    elif "!!!SBtab" in doc_row_dq:
+                        self.document_format = "sbtab"
+                    else:
+                        self.document_format = None
+
+                    return doc_row_dq
+                elif str(entry).startswith('"!!!'):
+                    rm2 = row.replace('""', "#").replace('"', "")
+                    doc_row = rm2.replace("#", '"')
+                    doc_row_dq = self._dequote(doc_row)
+
+                    # determine if this is an sbtab or ObjTables Document
+                    if "!!!ObjTables" in doc_row_dq:
+                        self.document_format = "ObjTables"
+                    elif "!!!SBtab" in doc_row_dq:
+                        self.document_format = "sbtab"
+                    else:
+                        self.document_format = None
+
+                    return doc_row_dq
+
+    def _get_header_row(self):
+        """Extract the declaration row from the sbtab file."""
+        header_row = None
+        # Find header row
+        for row in self.table:
+            for entry in row:
+                if str(entry).startswith("!!") and not str(entry).startswith("!!!"):
+                    header_row = "".join(row).rstrip("\n")
+                    break
+                elif str(entry).startswith("'!!") and not str(entry).startswith("'!!!"):
+                    rm1 = entry.replace("''", "#")
+                    rm2 = rm1.replace("'", "")
+                    header_row = rm2.replace("#", "'")
+                    break
+
+        # Save string or raise error
+        if not header_row:
+            raise SBtabError("""This is not a valid sbtab table, please use
+            validator to check format or have a look in the specification!""")
+
+        header_row_dq = self._dequote(header_row)
+
+        # determine if this is an sbtab or ObjTables Document
+        if "!!ObjTables" in header_row_dq:
+            self.table_format = "ObjTables"
+        elif "!!SBtab" in header_row_dq:
+            self.table_format = "sbtab"
+        else:
+            raise SBtabError("""This is not a valid sbtab table, please use
+            validator to check format or have a look in the specification!""")
+
+        return header_row_dq
+
+    def _dequote(self, row):
+        """
+        Bring consistency in the multifarious quotation mark problems.
+
+        Bring consistency in the multifarious quotation mark problems.
+        """
+        stupid_quotes = [
+            "\xe2\x80\x9d",
+            "\xe2\x80\x98",
+            "\xe2\x80\x99",
+            "\xe2\x80\x9b",
+            "\xe2\x80\x9c",
+            "\xe2\x80\x9f",
+            '"',
+            "\xe2\x80\xb2",
+            "\xe2\x80\xb3",
+            "\xe2\x80\xb4",
+            "\xe2\x80\xb5",
+            "\xe2\x80\xb6",
+            "\xe2\x80\xb7",
+        ]
+
+        for squote in stupid_quotes:
+            try:
+                row = row.replace(squote, "'")
+            except Exception:
+                pass
+
+        return row
+
+    def _generate_random_table_id(self):
+        """
+        Generate a random TableID for backwards compatibility.
+
+        The attribute TableID is enforced in sbtab. But to remain backwards compatible,
+        we generate a random TableID if none is given in the input file.
+        """
+        import random
+
+        i = random.randint(0, 1000)
+        table_id = "ID_%s" % str(i)
+
+        return table_id
+
+    def _get_table_information(self):
+        """Read declaration row and store the sbtab table attributes."""
+        # Save table id, otherwise raise error
+        try:
+            table_id = self._get_custom_table_information("TableID")
+        except Exception:
+            table_id = self._generate_random_table_id()
+            if "TableID=" not in self.header_row:
+                self.header_row = (
+                    self.header_row.replace(self.delimiter, "").strip()
+                    + " TableID='%s'" % table_id
+                )
+
+        # Save table type, otherwise raise error
+        try:
+            if self.table_format == "sbtab":
+                table_type = self._get_custom_table_information("TableType")
+            elif self.table_format == "ObjTables":
+                table_type = self._get_custom_table_information("class")
+        except Exception:
+            raise SBtabError("The TableType of the sbtab is not defined!")
+
+        # Save table name, otherwise create name
+        try:
+            table_name = self._get_custom_table_information("TableName")
+        except Exception:
+            table_name = table_type.capitalize() + "_unnamed"
+            self.header_row += " TableName='%s'" % table_name
+
+        # Save table document, otherwise return None
+        try:
+            table_document = self._get_custom_table_information("Document")
+        except Exception:
+            table_document = None
+
+        # save table version, otherwise return None
+        try:
+            table_version = self._get_custom_table_information("SBtabVersion")
+        except Exception:
+            table_version = None
+
+        # save table version, otherwise return None
+        try:
+            standard_concentration = self._get_custom_table_information(
+                "StandardConcentration"
+            )
+        except Exception:
+            standard_concentration = None
+
+        # save date
+        try:
+            self.date = self._get_custom_table_information("Date")
+        except Exception:
+            now = datetime.datetime.now()
+            self.date = "-".join([str(now.year), str(now.month), str(now.day)])
+            if "Date=" not in self.header_row:
+                self.header_row = (
+                    self.header_row.replace(self.delimiter, "")
+                    + " Date='%s'" % self.date
+                )
+
+        return (
+            table_id,
+            table_type,
+            table_name,
+            table_document,
+            table_version,
+            standard_concentration,
+        )
+
+    def _get_custom_table_information(self, attribute_name):
+        """
+        Retrieve the value of a table attribute in the declaration line.
+
+        Parameters
+        ----------
+        attribute_name : str
+           Name of the table attribute.
+        """
+        if re.search("%s='([^']*)'" % attribute_name, self.header_row) is not None:
+            return re.search("%s='([^']*)'" % attribute_name, self.header_row).group(1)
+        else:
+            raise SBtabError(
+                """The %s of the sbtab is
+                                not defined!"""
+                % attribute_name
+            )
+
+    def _get_columns(self):
+        """Extract column headers, add mandatory first column name if necessary."""
+        # Save list of main columns
+        column_names = None
+        for row in self.table:
+            for _entry in row:
+                if str(row[0]).startswith("!") and not str(row[0]).startswith("!!"):
+                    column_names = list(filter(lambda a: a != "", row))
+                    break
+
+        if column_names is None:
+            raise SBtabError(
+                "No column header row (a row starting with a single '!') was found."
+            )
+
+        # Get column positions
+        columns = dict(map(reversed, enumerate(column_names)))
+
+        return column_names, columns
+
+    def _get_rows(self):
+        """Extract the rows of the sbtab."""
+        value_rows = []
+        # Add to comments, if row starts with '%'
+        self.comments = []
+
+        for row in self.table:
+            if str(row[0]).startswith("!"):
+                continue
+            elif str(row[0]).startswith("%"):
+                self.comments.append(list(row))
+            else:
+                if len(list(row)) >= len(self.columns):
+                    value_rows.append(list(row)[: len(self.columns)])
+                else:
+                    value_rows.append(
+                        list(row) + [""] * (len(self.columns) - len(list(row)))
+                    )
+
+        return value_rows
+
+    # Here, the sbtab API starts
+    def to_str(self):
+        """
+        Return the sbtab table as a string.
+
+        Returns: str
+            The sbtab table in form of a string.
+        """
+        table_string = [self.header_row]
+        table_string.append("\t".join(self.columns))
+        for row in self.value_rows:
+            row = "\t".join(row)
+            table_string.append(row)
+
+        return "\n".join(table_string)
+
+    def change_attribute(self, attribute, value):
+        """
+        Change the value of an sbtab attribute.
+
+        Parameters
+        ----------
+        attribute : str
+            Attribute from the sbtab object's declaration row.
+        value: str
+            Value that the attribute should take.
+        """
+        att_value_new = "%s='%s'" % (attribute, value)
+
+        match = re.search(_attribute_pattern(attribute), self.header_row)
+        if match is None:
+            self.header_row = self.header_row + " " + att_value_new
+        else:
+            self.header_row = (
+                self.header_row[: match.start()]
+                + att_value_new
+                + self.header_row[match.end() :]
+            )
+
+    def set_filename(self, filename):
+        """
+        Set the filename of the sbtab.
+
+        Parameters
+        ----------
+        filename: str or Path
+            New filename for the sbtab object.
+        """
+        self.filename = Path(filename)
+        # validate file extension
+        self._validate_extension()
+
+    def add_sbtab_string(self, sbtab_string, definitions_file=None):
+        """Set the content of the sbtab Table in form of a string."""
+        self.table_string = sbtab_string
+        # validate singular sbtab
+        self._singular()
+
+        # process string
+        self.delimiter = utils.check_delimiter(sbtab_string)
+        self.preprocess = self._preprocess_table_string(sbtab_string)
+        self.table = self._cut_table_string(self.preprocess)
+
+        # Initialise table
+        self._initialize_table()
+
+    def unset_attribute(self, attribute):
+        """
+        Remove an attribute from sbtab declaration row.
+
+        Parameters
+        ----------
+        attribute : str
+            Attribute that shall be removed from the sbtab object's declaration row.
+        """
+        obligatory_attributes = ["TableType", "TableID"]
+        if attribute in obligatory_attributes:
+            raise SBtabError(
+                "Attribute %s cannot be removed as it is obligatory." % attribute
+            )
+
+        match = re.search(_attribute_pattern(attribute), self.header_row)
+        if match is None:
+            raise SBtabError(
+                "Attribute %s is not in the header of the SBtabTable." % attribute
+            )
+        start = match.start()
+        if self.header_row[start - 1 : start] == " ":
+            start -= 1
+        self.header_row = self.header_row[:start] + self.header_row[match.end() :]
+
+    def get_attribute(self, attribute, default=_MISSING):
+        """
+        Return the value of an sbtab attribute.
+
+        Parameters
+        ----------
+        attribute : str
+            Attribute from the sbtab object's declaration row.
+        default : object
+            Returned if the attribute is absent. If no default is given, a
+            missing attribute raises SBtabError.
+
+        Returns: str
+            Value of the requested attribute.
+        """
+        match = re.search(_attribute_pattern(attribute), self.header_row)
+        if match is not None:
+            return match.group(1)
+        if default is not _MISSING:
+            return default
+        raise SBtabError(
+            "The attribute %s was not found in the header row." % attribute
+        )
+
+    @property
+    def column_names(self):
+        """
+        The column names without their leading '!', in table order.
+
+        Returns: list of str
+            A new list; modifying it does not change the table.
+        """
+        return [_bare_column_name(column) for column in self.columns]
+
+    def to_dict_rows(self, strip=True):
+        """
+        Return the rows as dictionaries keyed by column name (without the '!').
+
+        Every dictionary has every column as a key. The dictionaries are copies:
+        modifying them does not change the table; use change_value_by_name for
+        that.
+
+        Parameters
+        ----------
+        strip : bool
+            Strip leading and trailing whitespace from every value.
+
+        Returns: list of dict
+            One dictionary per row, e.g. {'ID': 'R1', 'ReactionFormula': 'A <=> B'}.
+        """
+        names = self.column_names
+        dict_rows = []
+        for row in self.value_rows:
+            values = [str(value) for value in row[: len(names)]]
+            values += [""] * (len(names) - len(values))
+            if strip:
+                values = [value.strip() for value in values]
+            dict_rows.append(dict(zip(names, values)))
+        return dict_rows
+
+    def change_value(self, row, column, new):
+        """
+        Change a single value in the sbtab table by position in the table.
+
+        Parameters
+        ----------
+        row : int
+            Number of rows in the table. First row is number 1.
+        column : int
+            Number of columns in the table. First column is number 1.
+        new : str
+            New entry.
+        """
+        try:
+            self.value_rows[row - 1]
+        except Exception:
+            raise SBtabError("The sbtab has only %s rows." % len(self.value_rows))
+        try:
+            self.columns[column - 1]
+        except Exception:
+            raise SBtabError("The sbtab has only %s columns." % len(self.columns))
+
+        try:
+            self.value_rows[row - 1][column - 1] = str(new)
+        except Exception:
+            raise SBtabError("Could not set the given value.")
+
+        return True
+
+    def change_value_by_name(self, name, column_name, new):
+        """
+        Change single value in the sbtab by column name and first row entry name.
+
+        Parameters
+        ----------
+        row : str
+            Name of the entry in the ID column.
+        column : str
+            Name of the column (with '!').
+        new : str
+            New entry.
+        """
+        try:
+            self.columns_dict[column_name]
+        except Exception:
+            raise SBtabError("The column %s is not in the sbtab." % column_name)
+
+        success = False
+        col = self.columns_dict[column_name]
+        for r in self.value_rows:
+            if r[0] == name:
+                r[col] = str(new)
+                success = True
+
+        if not success:
+            raise SBtabError("Row %s was not found in the sbtab." % name)
+
+        return True
+
+    def create_list(self):
+        """
+        Create a list object of the sbtab table object.
+
+        Returns: list
+            List containing of sbtab content: [declaration row, columns, value_rows]
+        """
+        # Create new list
+        sbtab_list = []
+
+        # Append the parts header row, main column row and
+        # value rows to the list
+        sbtab_list.append([self.header_row])
+        sbtab_list.append(self.columns)
+        sbtab_list.append(self.value_rows)
+
+        return sbtab_list
+
+    def add_row(self, row_list, position=None):
+        """
+        Add a row to the table, if position is None at the end of it.
+
+        Parameters
+        ----------
+        row_list : list
+            List of strings, containing the entries of the new row.
+        position : int
+            Position of new row in the table, 0 is on top.
+        """
+        if not isinstance(row_list, list):
+            raise SBtabError("%s is not a list" % row_list)
+
+        if len(row_list) != len(self.columns):
+            raise SBtabError("Given row %s has not the correct length." % row_list)
+
+        if position is not None and not isinstance(position, int):
+            raise SBtabError("Please provide an integer row position.")
+
+        for element in row_list:
+            if not isinstance(element, str):
+                raise SBtabError("Please only provide string elements in the list")
+
+        # If no position is set, add new row to the end
+        if position is None:
+            self.value_rows.append(row_list)
+        else:
+            self.value_rows.insert(position, row_list)
+
+        return True
+
+    def remove_row(self, position):
+        """
+        Remove one row from the table.
+
+        Parameters
+        ----------
+        position : int
+            Position of row to be removed. Starting with 1.
+        """
+        if not isinstance(position, int):
+            raise SBtabError("Please provide an integer row position.")
+
+        if position > len(self.value_rows):
+            raise SBtabError("The sbtab only has %s row/s." % len(self.value_rows))
+
+        del self.value_rows[position - 1]
+
+        return True
+
+    def add_column(self, column_list, position=None):
+        """
+        Add a column to the table, if position is None at the end of it.
+
+        Parameters
+        ----------
+        column_list : list
+            List of strings, containing the entries of the new column.
+        position : int
+            Position of new column in the table, 0 is right.
+        """
+        if not isinstance(column_list, list):
+            raise SBtabError("%s is not a list" % column_list)
+
+        if len(column_list) != (len(self.value_rows) + 1):
+            raise SBtabError("The given column list has not the correct length.")
+
+        if position is not None and not isinstance(position, int):
+            raise SBtabError("Please provide an integer column position.")
+
+        # If no position is set, add new column to the end
+        if not position:
+            for i, row in enumerate(self.value_rows):
+                row.append(str(column_list[i + 1]))
+            self.columns_dict[str(column_list[0])] = len(self.columns)
+            self.columns.append(str(column_list[0]))
+        else:
+            for i, row in enumerate(self.value_rows):
+                row.insert(position - 1, str(column_list[i + 1]))
+            self.columns_dict[str(column_list[0])] = position - 1
+            self.columns.insert(position - 1, str(column_list[0]))
+
+        return True
+
+    def remove_column(self, position):
+        """
+        Remove column from the table.
+
+        Parameters
+        ----------
+        position : int
+            Position of column to be removed. Sarting with 1.
+        """
+        if not isinstance(position, int):
+            raise SBtabError("Please provide an integer column position.")
+
+        if position > len(self.columns):
+            raise SBtabError(
+                "There are only %s columns in the sbtab" % str(len(self.columns))
+            )
+
+        # Remove entries on position
+        for row in self.value_rows:
+            del row[position - 1]
+
+        # Remove column from column list
+        column_to_remove = self.columns[position - 1]
+        del self.columns[position - 1]
+
+        # Remove column from columns dict
+        self.columns_dict.pop(column_to_remove)
+
+        return True
+
+    def write(self, filename):
+        """
+        Write sbtab to hard disk.
+
+        Parameters
+        ----------
+        filename: str or Path
+            Name for the output file.
+        """
+        path = Path(filename)
+        if path.suffix not in {".tsv", ".csv"}:
+            if self.delimiter == "\t":
+                path = path.with_suffix(".tsv")
+            elif self.delimiter in {",", ";"}:
+                path = path.with_suffix(".csv")
+            else:
+                raise SBtabError(
+                    "The file extension is missing and the delimiter is no standard."
+                )
+
+        try:
+            table_string = self.to_str().replace("^M", "\n")
+            path.write_text(table_string)
+            return True
+        except Exception:
+            raise SBtabError("The file could not be written.")
+
+    def transpose_table(self):
+        """
+        Transpose sbtab table. Switch columns and rows.
+
+        Returns: sbtab.SBtabTable
+            sbtab object with transposed content.
+        """
+        # Initialize new table data
+        trans_columns = []
+        trans_columns_dict = {}
+        trans_value_rows = []
+
+        # Save old table data
+        columns = self.columns
+        value_rows = self.value_rows
+
+        # Append first entry to new column
+        trans_columns.append(columns.pop(0))
+
+        # Set new rows
+        for column in columns:
+            trans_value_rows.append([column])
+
+        # Set new values in tables
+        for row in value_rows:
+            trans_columns.append(row.pop(0))
+            for i, entry in enumerate(row):
+                trans_value_rows[i].append(entry)
+
+        # Write new columns dict
+        for i, column in enumerate(trans_columns):
+            trans_columns_dict[column] = i
+
+        # Overwrite old table data
+        self.columns = trans_columns
+        self.columns_dict = trans_columns_dict
+        self.value_rows = trans_value_rows
+
+        return True
+
+    def to_data_frame(self):
+        """
+        Export sbtab table object as pandas dataframe.
+
+        Returns: pandas.DataFrame
+            sbtab table object as pandas dataframe.
+        """
+        pd = utils.require_optional("pandas", "pandas")
+        try:
+            # value_rows, unlike the raw parsed grid, exists on every table,
+            # including those built by from_data_frame and from_rows
+            rows = [list(row) for row in self.value_rows]
+            column_names = self.column_names
+            n_cols = max(map(len, rows), default=len(column_names))
+            while len(column_names) < n_cols:
+                column_names += ["Col%d" % len(column_names)]
+            df = pd.DataFrame(data=rows, columns=column_names)
+            return df
+        except Exception:
+            raise SBtabError("Pandas dataframe could not be built.")
+
+    @staticmethod
+    def from_data_frame(
+        df,
+        table_id,
+        table_type,
+        table_name=None,
+        document_name=None,
+        document=None,
+        unit=None,
+        sbtab_version="1.0",
+    ) -> "SBtabTable":
+        """
+        Create sbtab table object from pandas dataframe.
+
+        Column names are expected to start with '!' (e.g. '!QuantityType');
+        the '!' is added where it is missing. Values are converted to str.
+
+        Parameters
+        ----------
+        df : pandas.DataFrame
+            Dataframe of the Python library pandas.
+        table_id: str
+            Mandatory table ID for the sbtab object.
+        table_type: str
+            Mandatory table type for the sbtab object.
+        table_name: str
+            Optional table name for the sbtab object.
+        document_name: str
+            Optional document name for the sbtab object.
+        document: str
+            Optional document for the sbtab object.
+        unit: str
+            Optional unit for an sbtab TableType Quantity.
+        sbtab_version: str
+            Optional sbtab Version.
+
+        Returns: sbtab.SBtabTable
+            sbtab table object created from pandas dataframe.
+        """
+        return SBtabTable.from_rows(
+            [str(column) for column in df.columns],
+            df.values.tolist(),
+            table_id=table_id,
+            table_type=table_type,
+            table_name=table_name,
+            document_name=document_name,
+            document=document,
+            unit=unit,
+            sbtab_version=sbtab_version,
+        )
+
+    @classmethod
+    def from_rows(
+        cls,
+        columns,
+        rows,
+        table_id,
+        table_type,
+        table_name=None,
+        document_name=None,
+        document=None,
+        unit=None,
+        sbtab_version="1.0",
+        **attributes,
+    ) -> "SBtabTable":
+        """
+        Create sbtab table object from column names and rows, without pandas.
+
+        The table is built directly, not parsed from text, so unlike a parsed
+        table no Date attribute is added to its declaration row.
+
+        Parameters
+        ----------
+        columns : list of str
+            Column names, with or without the leading '!' (added if missing).
+        rows : list
+            Each row is either a list of values, used by position (padded with
+            '' or truncated to the number of columns), or a dict keyed by
+            column name without the '!' (missing columns become '', unknown
+            keys raise SBtabError). All values are converted to str.
+        table_id: str
+            Mandatory table ID for the sbtab object.
+        table_type: str
+            Mandatory table type for the sbtab object.
+        table_name: str
+            Optional table name for the sbtab object (defaults to table_id).
+        document_name: str
+            Optional document name for the sbtab object.
+        document: str
+            Optional document for the sbtab object.
+        unit: str
+            Optional unit for an sbtab TableType Quantity.
+        sbtab_version: str
+            Optional sbtab Version.
+        **attributes: str
+            Further declaration row attributes, in the order given,
+            e.g. StandardConcentration='M'.
+
+        Returns: sbtab.SBtabTable
+            sbtab table object created from the rows.
+        """
+        column_list = [
+            column if column.startswith("!") else "!" + column for column in columns
+        ]
+        bare_names = [_bare_column_name(column) for column in column_list]
+        n_cols = len(column_list)
+
+        value_rows = []
+        for row in rows:
+            if isinstance(row, Mapping):
+                unknown = [key for key in row if key not in bare_names]
+                if unknown:
+                    raise SBtabError(
+                        "Unknown column(s) %s; the columns are %s."
+                        % (", ".join(map(str, unknown)), ", ".join(bare_names))
+                    )
+                values = [row.get(name, "") for name in bare_names]
+            else:
+                values = list(row)[:n_cols]
+                values += [""] * (n_cols - len(values))
+            value_rows.append([str(value) for value in values])
+
+        sbtab = cls()
+
+        sbtab.table_id = table_id
+        sbtab.table_type = table_type
+        sbtab.table_name = table_name or table_id
+        sbtab.table_document = document
+        sbtab.table_version = sbtab_version
+
+        header = [
+            ("TableID", sbtab.table_id),
+            ("TableType", sbtab.table_type),
+            ("TableName", sbtab.table_name),
+            ("SBtabVersion", sbtab.table_version),
+        ]
+        if document_name:
+            header += [("DocumentName", document_name)]
+        if document:
+            header += [("Document", sbtab.table_document)]
+        if unit:
+            header += [("Unit", unit)]
+        header += list(attributes.items())
+        header_strings = ["!!SBtab"] + list(map(lambda x: "%s='%s'" % x, header))
+
+        sbtab.doc_row = None
+        sbtab.header_row = " ".join(header_strings)
+
+        sbtab.columns = column_list
+        sbtab.columns_dict = dict(map(reversed, enumerate(column_list)))
+        sbtab.value_rows = value_rows
+
+        return sbtab
+
+
+class SBtabDocument:
+    """The sbtab document class can consist of one or more sbtab Table objects."""
+
+    def __init__(
+        self, name=None, sbtab_init=None, filename=None, definitions_file=None
+    ):
+        """
+        Create SBtabDocument with an optional sbtab table object.
+
+        Parameters
+        ----------
+        name: str
+            Name for the sbtab document.
+        sbtab_init: str | sbtab.SBtabTable
+            Initial sbtab table as either string or sbtab table object
+        filename: str
+            If sbtab_init is string, also provide a fiename.
+        """
+        if filename:
+            self.filename = filename
+        else:
+            self.filename = None
+        self.sbtabs = []
+        self.id_to_sbtab = {}
+        self.name_to_sbtab = {}
+        self.type_to_sbtab = {}
+        self.sbtab_filenames = []
+        self.doc_row = False
+        self.document_format = None
+
+        if name:
+            self.name = name
+            self._get_doc_row_attributes()
+        else:
+            self.name = None
+
+        # if there is an initial sbtab given, see if it is
+        # a string or an sbtab
+        if sbtab_init and isinstance(sbtab_init, str):
+            self.add_sbtab_string(sbtab_init, filename, definitions_file)
+        elif sbtab_init:
+            self.add_sbtab(sbtab_init, definitions_file)
+
+        self.object_type = "doc"
+
+    def add_sbtab(self, sbtab, definitions_file=None):
+        """
+        Add an sbtab Table object to the sbtab Document.
+
+        Parameters
+        ----------
+        sbtab: sbtab.SBtabTable
+            sbtab table object to be added to the document.
+        """
+        if not self.filename:
+            self.filename = sbtab.filename
+
+        if sbtab.table_id in self.id_to_sbtab.keys():
+            raise SBtabError(
+                "A table with the ID %s is already in the document. Table IDs need"
+                " to be unique within one document." % sbtab.table_id
+            )
+
+        valid_type = self.check_type_validity(sbtab.table_type, definitions_file)
+        if valid_type:
+            self.name_to_sbtab[sbtab.table_name] = sbtab
+            self.id_to_sbtab[sbtab.table_id] = sbtab
+            self.sbtabs.append(sbtab)
+            self.sbtab_filenames.append(sbtab.filename)
+            if sbtab.table_type in self.type_to_sbtab:
+                tabs = self.type_to_sbtab[sbtab.table_type]
+                tabs.append(sbtab)
+                self.type_to_sbtab[sbtab.table_type] = tabs
+            else:
+                self.type_to_sbtab[sbtab.table_type] = [sbtab]
+
+            self._get_doc_row_attributes()
+            return True
+
+    def add_sbtab_string(self, sbtab_string, filename, definitions_file=None):
+        """
+        Add one or multiple sbtab files as a string.
+
+        Parameters
+        ----------
+        sbtab_string: str
+            One string holding one or more sbtab tables.
+        filename: str
+            Name of the given sbtab.
+        """
+        # set filename if not given
+        if not filename:
+            sbtab_count = len(self.sbtabs)
+            filename = "unnamed_sbtab_%s.tsv" % (str(sbtab_count))
+
+        if not self.filename:
+            self.filename = filename
+        if not self.name:
+            self.name = filename
+
+        # see if there are more than one SBtabs in the string
+        try:
+            sbtab_amount = utils.count_tabs(sbtab_string)
+        except Exception:
+            raise SBtabError("The sbtab file could not be read properly.")
+
+        # here, we find a possible doc row
+        for row in sbtab_string.split("\n"):
+            if row.startswith("!!!"):
+                self.doc_row = self._dequote(row)
+                break
+            elif row.startswith('"!!!'):
+                rm1 = row.replace('""', "#")
+                rm2 = rm1.replace('"', "")
+                self.doc_row = self._dequote(rm2.replace("#", '"'))
+                break
+            else:
+                self.doc_row = None
+                self.document_format = None
+
+        # determine if this is an sbtab or ObjTables Document
+        if self.doc_row:
+            if "!!!ObjTables" in self.doc_row:
+                self.document_format = "ObjTables"
+            elif "!!!SBtab" in self.doc_row:
+                self.document_format = "sbtab"
+
+        # if there are more than one SBtabs, cut them in single SBtabs
+        try:
+            if sbtab_amount > 1:
+                sbtab_strings = utils.split_sbtabs(sbtab_string)
+                for i, sbtab_s in enumerate(sbtab_strings):
+                    name_single = str(i) + "_" + str(self.filename)
+                    sbtab_single = SBtabTable(sbtab_s, name_single)
+                    logging.debug(
+                        "name = %s, type = %s"
+                        % (sbtab_single.table_name, sbtab_single.table_type)
+                    )
+                    self.add_sbtab(sbtab_single, definitions_file)
+            else:
+                sbtab = SBtabTable(sbtab_string, filename)
+                self.add_sbtab(sbtab)
+        except Exception as e:
+            raise SBtabError(
+                "The sbtab Table object could not be created properly: " + str(e)
+            )
+        return True
+
+    def _dequote(self, row):
+        """Bring consistency in the multifarious quotation mark problems."""
+        stupid_quotes = [
+            '"',
+            "\xe2\x80\x9d",
+            "\xe2\x80\x98",
+            "\xe2\x80\x99",
+            "\xe2\x80\x9b",
+            "\xe2\x80\x9c",
+            "\xe2\x80\x9f",
+            "\xe2\x80\xb2",
+            "\xe2\x80\xb3",
+            "\xe2\x80\xb4",
+            "\xe2\x80\xb5",
+            "\xe2\x80\xb6",
+            "\xe2\x80\xb7",
+        ]
+
+        for squote in stupid_quotes:
+            try:
+                row = row.replace(squote, "'")
+            except Exception:
+                pass
+
+        row = row.replace("\n", "")
+
+        return row
+
+    def check_type_validity(self, ttype, definitions_file=None):
+        """
+        Check if the given table type is supported by default.
+
+        Parameters
+        ----------
+        ttype: str
+            Table type to be tested.
+
+        Returns: Bool
+            Flag that indicates if the given table type is supported by default.
+
+        """
+        try:
+            supported_types = utils.extract_supported_table_types(definitions_file)
+        except Exception:
+            raise SBtabError(
+                "The definition file could not be found to"
+                " establish supported table types."
+            )
+
+        if ttype in supported_types:
+            return True
+        else:
+            raise SBtabError(
+                "The table type %s is not supported. Make sure to provide a"
+                " definition file that contains this table type." % ttype
+            )
+
+    def _get_doc_row_attributes(self):
+        """Read content of the !!!-document declaration row."""
+        now = datetime.datetime.now()
+        self.date = "-".join([str(now.year), str(now.month), str(now.day)])
+
+        if not self.doc_row:
+            self.doc_row = "!!!SBtab DocumentName='%s' SBtabVersion='1.0' Date='%s'" % (
+                self.name,
+                self.date,
+            )
+        else:
+            # save document name, otherwise raise error
+            # (overrides name given at document initialisation)
+            try:
+                self.name = self.get_custom_doc_information("DocumentName")
+            except Exception:
+                pass
+
+            # save SBtabVersion
+            try:
+                self.version = self.get_custom_doc_information("SBtabVersion")
+            except Exception:
+                self.version = None
+
+            # save date
+            try:
+                self.date = self.get_custom_doc_information("Date")
+            except Exception:
+                if "Date=" not in self.doc_row:
+                    self.doc_row = self.doc_row + " Date='%s'" % self.date
+
+            # save document type
+            try:
+                self.doc_type = self.get_custom_doc_information("DocumentType")
+            except Exception:
+                self.doc_type = None
+
+    def change_attribute(self, attribute, value):
+        """
+        Change the value of an sbtab attribute.
+
+        Parameters
+        ----------
+        attribute: str
+            Attribute from the sbtab document object's declaration row.
+        value: str
+            Value for the attribute.
+        """
+        try:
+            att_value_new = "%s='%s'" % (attribute, value)
+        except Exception:
+            raise SBtabError("Please provide only strings as attribute and value.")
+
+        match = re.search(_attribute_pattern(attribute), self.doc_row)
+        if match is None:
+            self.doc_row = self.doc_row + " " + att_value_new
+        else:
+            self.doc_row = (
+                self.doc_row[: match.start()]
+                + att_value_new
+                + self.doc_row[match.end() :]
+            )
+
+    def unset_attribute(self, attribute):
+        """
+        Remove attribute from sbtab document object's declaration row.
+
+        Parameters
+        ----------
+        attribute: str
+            Attribute that shall be removed.
+        """
+        obligatory_attributes = ["DocumentName"]
+        if attribute in obligatory_attributes:
+            raise SBtabError(
+                "Attribute %s cannot be removed as it is obligatory." % attribute
+            )
+
+        match = re.search(_attribute_pattern(attribute), self.doc_row)
+        if match is None:
+            raise SBtabError(
+                "Attribute %s is not in the doc row of the SBtabDocument." % attribute
+            )
+        start = match.start()
+        if self.doc_row[start - 1 : start] == " ":
+            start -= 1
+        self.doc_row = self.doc_row[:start] + self.doc_row[match.end() :]
+
+    def get_attribute(self, attribute, default=_MISSING):
+        """
+        Return the value of an sbtab attribute.
+
+        Parameters
+        ----------
+        attribute: str
+            Attribute from the sbtab document object's declaration row.
+        default : object
+            Returned if the attribute is absent. If no default is given, a
+            missing attribute raises SBtabError.
+
+        Returns: str
+            Value of the requested attribute.
+        """
+        match = re.search(_attribute_pattern(attribute), self.doc_row or "")
+        if match is not None:
+            return match.group(1)
+        if default is not _MISSING:
+            return default
+        raise SBtabError("The attribute %s was not found in the doc row." % attribute)
+
+    def set_version(self, version):
+        """
+        Set SBtabVersion of the document.
+
+        Parameters
+        ----------
+        version: str
+            Version number of sbtab document.
+        """
+        try:
+            self.version = version
+        except Exception:
+            raise SBtabError("Version could not be set to %s" % version)
+
+    def set_date(self, date):
+        """
+        Set date of the document.
+
+        Parameters
+        ----------
+        date: str
+            Date of the sbtab document.
+        """
+        try:
+            self.date = date
+        except Exception:
+            raise SBtabError("Date could not be set to %s" % date)
+
+    def set_doc_type(self, doc_type):
+        """
+        Set the type of the document.
+
+        Parameters
+        ----------
+        doc_type: str
+            Type of the sbtab document.
+        """
+        try:
+            self.doc_type = doc_type
+        except Exception:
+            raise SBtabError("Doc type could not be set to %s" % doc_type)
+
+    def remove_sbtab_by_name(self, name):
+        """
+        Remove sbtab Table from sbtab Document.
+
+        Parameters
+        ----------
+        name: str
+            Name of the sbtab table to be removed.
+        """
+        for i, sbtab in enumerate(self.sbtabs):
+            if sbtab.table_name == name:
+                del self.sbtabs[i]
+                del self.name_to_sbtab[sbtab.table_name]
+                del self.id_to_sbtab[sbtab.table_id]
+                del self.sbtab_filenames[i]
+                tabs = self.type_to_sbtab[sbtab.table_type]
+                for tab in tabs:
+                    if tab.table_name == sbtab.table_name:
+                        tabs.remove(tab)
+                        break
+
+                self.type_to_sbtab[sbtab.table_type] = tabs
+                break
+
+        return True
+
+    def get_sbtab_by_name(self, name):
+        """
+        Return sbtab table object by given name.
+
+        Parameters
+        ----------
+        name: str
+            Name of sbtab table to be returned.
+
+        Returns: sbtab.SBtabTable
+            sbtab table object of requested name.
+        """
+        try:
+            return self.name_to_sbtab[name]
+        except Exception:
+            return None
+
+    def get_sbtab_by_id(self, name):
+        """
+        Return sbtab table object by given ID.
+
+        Parameters
+        ----------
+        name: str
+            TableID of a sbtab table object.
+
+        Returns: sbtab.SBtabTable
+            sbtab table object of requested ID.
+        """
+        try:
+            return self.id_to_sbtab[name]
+        except Exception:
+            return None
+
+    def get_sbtab_by_type(self, ttype):
+        """
+        Return list of sbtab objects by given table type.
+
+        Parameters
+        ----------
+        ttype: str
+            Supported sbtab table type.
+
+        Returns: list
+            List of sbtab.SBtabTable objects of the requested table type.
+        """
+        try:
+            return self.type_to_sbtab[ttype]
+        except Exception:
+            return None
+
+    def set_filename(self, filename):
+        """
+        Set filename of sbtab document.
+
+        Parameters
+        ----------
+        filename: str or Path
+            Filename for the sbtab document.
+        """
+        self.filename = Path(filename)
+
+    def set_name(self, name):
+        """
+        Set name of sbtab document.
+
+        Parameters
+        ----------
+        name: str
+            Name for the sbtab document.
+        """
+        self.name = name
+
+    def write(self, filename=None):
+        """
+        Write SBtabDocument to hard disk.
+
+        Parameters
+        ----------
+        filename: str or Path
+            Name for the output file.
+        """
+        path = Path(filename if filename is not None else self.filename)
+        if path.suffix not in {".tsv", ".csv"}:
+            delimiter = self.sbtabs[0].delimiter
+            if delimiter == "\t":
+                path = path.with_suffix(".tsv")
+            elif delimiter in {",", ";"}:
+                path = path.with_suffix(".csv")
+            else:
+                raise SBtabError(
+                    "The file extension is missing and the delimiter is not set."
+                )
+
+        try:
+            path.write_text(self.to_str())
+            return True
+        except Exception:
+            raise SBtabError("The file could not be written.")
+
+    def to_str(self):
+        """
+        Return sbtab Document as one string.
+
+        Returns: str
+            sbtab.SBtabDocument as string representation.
+        """
+        sbtab_document = self.doc_row + "\r\n"
+        for sbtab in self.sbtabs:
+            sbtab_document += sbtab.to_str() + "\n\n"
+
+        return sbtab_document
+
+    def get_custom_doc_information(self, attribute_name, test_row=None):
+        """
+        Retrieve the value of a doc attribute in the sbtab document declaration row.
+
+        Parameters
+        ----------
+        attribute_name: str
+           Name of the requested attribute.
+
+        Returns: str
+           Value of the requested attribute.
+        """
+        if test_row:
+            doc_row = test_row
+        else:
+            doc_row = self.doc_row
+
+        if re.search("%s='([^']*)'" % attribute_name, doc_row) is not None:
+            return re.search("%s='([^']*)'" % attribute_name, doc_row).group(1)
+        else:
+            raise SBtabError(
+                """The %s of the Document is
+                                not defined!"""
+                % attribute_name
+            )
+
+    def set_doc_row(self, new_doc_row):
+        """
+        Set a new sbtab document declaration row.
+
+        Parameters
+        ----------
+        new_doc_row: str
+            New sbtab document declaration row.
+        """
+        if not new_doc_row.startswith("!!!SBtab") and not new_doc_row.startswith(
+            "!!!ObjTables"
+        ):
+            raise SBtabError('A doc row needs to be preceded with "!!!SBtab".')
+
+        if "DocumentName=" not in new_doc_row:
+            raise SBtabError("A doc row needs to define the DocumentName attribute.")
+
+        self.doc_row = new_doc_row
+        self._get_doc_row_attributes()