Skip to content

API

API Documentation

This package contains functions to generate iTOL configuration files.

ConfigWriter

Bases: ABC

Abstract base class for iTOL configuration file writers.

Source code in itol_config/interfaces/base_interface.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class ConfigWriter(ABC):
    """
    Abstract base class for iTOL configuration file writers.
    """
    def __init__(self, data: dict, label: str, colour_lookup: Optional[dict] = None):
        """
        Initialise a ConfigWriter object for a simple dictionary dataset.

        Parameters
        ----------
        data : dict
            Dictionary containing the values to be coloured.
        label : str
            Label for the colour strip.
        colour_lookup : Optional[dict]
            Dictionary of colours for each unique value in the data.
            If not provided, it will be generated.

        Returns
        -------
        None
        """
        self.data = data
        self.label = label
        if colour_lookup is None:
            colour_lookup = get_colour_lookup(data.values())
        self.colour_lookup = colour_lookup
        self.config = {
            "dataset_label":self.label,
            "legend_title":self.label,
            "legend_shapes":"\t".join(["1" for _ in self.colour_lookup]),
            "legend_labels":"\t".join([str(x) for x in self.colour_lookup]),
            "legend_colours":"\t".join([self.colour_lookup[x] for x in self.colour_lookup])
        }

    @abstractmethod
    def write(self, outfile: str) -> None:
        """
        Write the iTOL configuration file.

        Parameters
        ----------
        outfile : str
            Output file name.

        Returns
        -------
        None
        """
        raise NotImplementedError

__init__(data, label, colour_lookup=None)

Initialise a ConfigWriter object for a simple dictionary dataset.

Parameters:

Name Type Description Default
data dict

Dictionary containing the values to be coloured.

 required
label str

Label for the colour strip.

 required
colour_lookup Optional[dict]

Dictionary of colours for each unique value in the data. If not provided, it will be generated.

 None

Returns:

Type Description
None
Source code in itol_config/interfaces/base_interface.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def __init__(self, data: dict, label: str, colour_lookup: Optional[dict] = None):
    """
    Initialise a ConfigWriter object for a simple dictionary dataset.

    Parameters
    ----------
    data : dict
        Dictionary containing the values to be coloured.
    label : str
        Label for the colour strip.
    colour_lookup : Optional[dict]
        Dictionary of colours for each unique value in the data.
        If not provided, it will be generated.

    Returns
    -------
    None
    """
    self.data = data
    self.label = label
    if colour_lookup is None:
        colour_lookup = get_colour_lookup(data.values())
    self.colour_lookup = colour_lookup
    self.config = {
        "dataset_label":self.label,
        "legend_title":self.label,
        "legend_shapes":"\t".join(["1" for _ in self.colour_lookup]),
        "legend_labels":"\t".join([str(x) for x in self.colour_lookup]),
        "legend_colours":"\t".join([self.colour_lookup[x] for x in self.colour_lookup])
    }

write(outfile) abstractmethod

Write the iTOL configuration file.

Parameters:

Name Type Description Default
outfile str

Output file name.

 required

Returns:

Type Description
None
Source code in itol_config/interfaces/base_interface.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
@abstractmethod
def write(self, outfile: str) -> None:
    """
    Write the iTOL configuration file.

    Parameters
    ----------
    outfile : str
        Output file name.

    Returns
    -------
    None
    """
    raise NotImplementedError

ConfigWriterMatrix

Bases: ABC

Abstract base class for iTOL configuration file writers.

Source code in itol_config/interfaces/base_interface.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
class ConfigWriterMatrix(ABC):
    """
    Abstract base class for iTOL configuration file writers.
    """
    def __init__(self, data: Dict[str,dict], label: str, colour_lookup: Optional[dict] = None):
        """
        Initialise a ConfigWriter for a matrix-type dataset.

        Parameters
        ----------
        data : dict
            Dictionary containing the values to be coloured.
        label : str
            Label for the colour strip.
        colour_lookup : Optional[dict]
            Dictionary of colours for each unique value in the data.
            If not provided, it will be generated.

        Returns
        -------
        None
        """
        self.data = data
        self.label = label
        first_row = list(data.values())[0]
        self.field_labels = list(first_row.keys())

        if colour_lookup is None:
            colour_lookup = get_colour_lookup(self.field_labels)
        self.colour_lookup = colour_lookup
        self.config = {
            "dataset_label":self.label,
            "field_labels":"\t".join([str(x) for x in self.field_labels]),
            "field_colours":"\t".join([self.colour_lookup[x] for x in self.field_labels])
        }

    @abstractmethod
    def write(self, outfile: str) -> None:
        """
        Write the iTOL configuration file.

        Parameters
        ----------
        outfile : str
            Output file name.

        Returns
        -------
        None
        """
        raise NotImplementedError

__init__(data, label, colour_lookup=None)

Initialise a ConfigWriter for a matrix-type dataset.

Parameters:

Name Type Description Default
data dict

Dictionary containing the values to be coloured.

 required
label str

Label for the colour strip.

 required
colour_lookup Optional[dict]

Dictionary of colours for each unique value in the data. If not provided, it will be generated.

 None

Returns:

Type Description
None
Source code in itol_config/interfaces/base_interface.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def __init__(self, data: Dict[str,dict], label: str, colour_lookup: Optional[dict] = None):
    """
    Initialise a ConfigWriter for a matrix-type dataset.

    Parameters
    ----------
    data : dict
        Dictionary containing the values to be coloured.
    label : str
        Label for the colour strip.
    colour_lookup : Optional[dict]
        Dictionary of colours for each unique value in the data.
        If not provided, it will be generated.

    Returns
    -------
    None
    """
    self.data = data
    self.label = label
    first_row = list(data.values())[0]
    self.field_labels = list(first_row.keys())

    if colour_lookup is None:
        colour_lookup = get_colour_lookup(self.field_labels)
    self.colour_lookup = colour_lookup
    self.config = {
        "dataset_label":self.label,
        "field_labels":"\t".join([str(x) for x in self.field_labels]),
        "field_colours":"\t".join([self.colour_lookup[x] for x in self.field_labels])
    }

write(outfile) abstractmethod

Write the iTOL configuration file.

Parameters:

Name Type Description Default
outfile str

Output file name.

 required

Returns:

Type Description
None
Source code in itol_config/interfaces/base_interface.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
@abstractmethod
def write(self, outfile: str) -> None:
    """
    Write the iTOL configuration file.

    Parameters
    ----------
    outfile : str
        Output file name.

    Returns
    -------
    None
    """
    raise NotImplementedError

ColourStripConfigWriter

Bases: ConfigWriter

Source code in itol_config/interfaces/colour_strip.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
class ColourStripConfigWriter(ConfigWriter):
    def write(self, outfile: str) -> None:
        """
        Parse the data to be coloured.

        Parameters
        ----------
        outfile : str
            Output file name.

        Returns
        -------
        None
        """
        with open(outfile,"w") as O:
            O.write(template % self.config)
            for index, value in self.data.items():
                O.write("%s\t%s\n" % (index,self.colour_lookup[value]))

write(outfile)

Parse the data to be coloured.

Parameters:

Name Type Description Default
outfile str

Output file name.

 required

Returns:

Type Description
None
Source code in itol_config/interfaces/colour_strip.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def write(self, outfile: str) -> None:
    """
    Parse the data to be coloured.

    Parameters
    ----------
    outfile : str
        Output file name.

    Returns
    -------
    None
    """
    with open(outfile,"w") as O:
        O.write(template % self.config)
        for index, value in self.data.items():
            O.write("%s\t%s\n" % (index,self.colour_lookup[value]))

TextLabelConfigWriter

Bases: ConfigWriter

Source code in itol_config/interfaces/text_label.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
class TextLabelConfigWriter(ConfigWriter):
    def write(self, outfile: str) -> None:
        """
        Parse the data to be coloured.

        Parameters
        ----------
        outfile : str
            Output file name.

        Returns
        -------
        None
        """
        with open(outfile,"w") as O:
            O.write(template % self.config)
            for index, value in self.data.items():
                O.write("%s\t%s\t-1\t%s\tnormal\t1\t0\n" % (index,self.data[index],self.colour_lookup[value]))

write(outfile)

Parse the data to be coloured.

Parameters:

Name Type Description Default
outfile str

Output file name.

 required

Returns:

Type Description
None
Source code in itol_config/interfaces/text_label.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
def write(self, outfile: str) -> None:
    """
    Parse the data to be coloured.

    Parameters
    ----------
    outfile : str
        Output file name.

    Returns
    -------
    None
    """
    with open(outfile,"w") as O:
        O.write(template % self.config)
        for index, value in self.data.items():
            O.write("%s\t%s\t-1\t%s\tnormal\t1\t0\n" % (index,self.data[index],self.colour_lookup[value]))

BinaryDataConfigWriter

Bases: ConfigWriterMatrix

Source code in itol_config/interfaces/binary_data.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
class BinaryDataConfigWriter(ConfigWriterMatrix):    
    def __init__(self, data: Dict[str,dict], label: str, colour_lookup: Optional[dict] = None, shape: int = 2,):
        """
        Initialise a ConfigWriter object.

        Parameters
        ----------
        data : dict
            Dictionary containing the values to be coloured.
        label : str
            Label for the colour strip.
        colour_lookup : Optional[dict]
            Dictionary of colours for each unique value in the data.
            If not provided, it will be generated.
        shape : int
            Shape of the field.

        Returns
        -------
        None
        """
        super().__init__(data,label,colour_lookup)
        self.config["field_shapes"] = "\t".join([str(shape) for _ in self.colour_lookup])
    def write(self, outfile: str) -> None:
        """
        Write the iTOL configuration file.

        Parameters
        ----------
        outfile : str
            Output file name.

        Returns
        -------
        None
        """
        with open(outfile,"w") as O:
            O.write(template % self.config)
            for index, values in self.data.items():
                binary_data = "\t".join([str(x) for x in values.values()])
                O.write("%s\t%s\n" % (index,binary_data))

__init__(data, label, colour_lookup=None, shape=2)

Initialise a ConfigWriter object.

Parameters:

Name Type Description Default
data dict

Dictionary containing the values to be coloured.

 required
label str

Label for the colour strip.

 required
colour_lookup Optional[dict]

Dictionary of colours for each unique value in the data. If not provided, it will be generated.

 None
shape int

Shape of the field.

 2

Returns:

Type Description
None
Source code in itol_config/interfaces/binary_data.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def __init__(self, data: Dict[str,dict], label: str, colour_lookup: Optional[dict] = None, shape: int = 2,):
    """
    Initialise a ConfigWriter object.

    Parameters
    ----------
    data : dict
        Dictionary containing the values to be coloured.
    label : str
        Label for the colour strip.
    colour_lookup : Optional[dict]
        Dictionary of colours for each unique value in the data.
        If not provided, it will be generated.
    shape : int
        Shape of the field.

    Returns
    -------
    None
    """
    super().__init__(data,label,colour_lookup)
    self.config["field_shapes"] = "\t".join([str(shape) for _ in self.colour_lookup])

write(outfile)

Write the iTOL configuration file.

Parameters:

Name Type Description Default
outfile str

Output file name.

 required

Returns:

Type Description
None
Source code in itol_config/interfaces/binary_data.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def write(self, outfile: str) -> None:
    """
    Write the iTOL configuration file.

    Parameters
    ----------
    outfile : str
        Output file name.

    Returns
    -------
    None
    """
    with open(outfile,"w") as O:
        O.write(template % self.config)
        for index, values in self.data.items():
            binary_data = "\t".join([str(x) for x in values.values()])
            O.write("%s\t%s\n" % (index,binary_data))