Skip to content

Other Utilities

theme

Colors and plotly themes of mesqual.

colors module-attribute

colors = ColorPalette

The color groups of the mesqual theme, for example colors.primary.teal.

plotly_theme_dark module-attribute

plotly_theme_dark = PlotlyTheme(default_colorway=QualitativeColors.default, font=dict(family='Inter, sans-serif', size=12, color=DarkGreyColors.text), paper_color=DarkGreyColors.background, background_color=DarkGreyColors.background, xaxis=dict(gridcolor=DarkGreyColors.gridlines, linecolor=DarkGreyColors.borders, zerolinecolor=DarkGreyColors.borders), yaxis=dict(gridcolor=DarkGreyColors.gridlines, linecolor=DarkGreyColors.borders, zerolinecolor=DarkGreyColors.borders), legend=dict(bgcolor='rgba(0,0,0,0)'))

Dark plotly theme: DarkGreyColors, the font Inter and the colorway QualitativeColors.default.

plotly_theme_light module-attribute

plotly_theme_light = PlotlyTheme(default_colorway=QualitativeColors.default, font=dict(family='Arial, sans-serif', size=12, color=LightGreyColors.text), paper_color=LightGreyColors.paper, background_color=LightGreyColors.background, xaxis=dict(gridcolor=LightGreyColors.gridlines, linecolor=LightGreyColors.borders, zerolinecolor=LightGreyColors.borders), yaxis=dict(gridcolor=LightGreyColors.gridlines, linecolor=LightGreyColors.borders, zerolinecolor=LightGreyColors.borders), legend=dict(bgcolor='rgba(255,255,255,0.6)'))

Light plotly theme: LightGreyColors, the font Arial and the colorway QualitativeColors.default.

PrimaryColors

Bases: ConstantsIterable

The primary colors of the mesqual theme.

Attributes:

Name Type Description
sky_blue

#0ea5e9.

teal

#14b8a6.

amber

#f59e0b.

violet

#8b5cf6.

rose

#dc2626.

green

#22c55e.

Source code in src/mesqual/utils/theme.py
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class PrimaryColors(ConstantsIterable):
    """The primary colors of the mesqual theme.

    Attributes:
        sky_blue: `#0ea5e9`.
        teal: `#14b8a6`.
        amber: `#f59e0b`.
        violet: `#8b5cf6`.
        rose: `#dc2626`.
        green: `#22c55e`.
    """

    sky_blue = '#0ea5e9'
    teal = '#14b8a6'
    amber = '#f59e0b'
    violet = '#8b5cf6'
    rose = '#dc2626'
    green = '#22c55e'

SequentialColors

Bases: ConstantsIterable

Sequential color scales from light to dark, seven hex colors each.

Attributes:

Name Type Description
sky_blue

Scale around PrimaryColors.sky_blue.

teal

Scale around PrimaryColors.teal.

amber

Scale around PrimaryColors.amber.

violet

Scale around PrimaryColors.violet.

rose

Scale around PrimaryColors.rose.

green

Scale around PrimaryColors.green.

default

sky_blue.

Source code in src/mesqual/utils/theme.py
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
class SequentialColors(ConstantsIterable):
    """Sequential color scales from light to dark, seven hex colors each.

    Attributes:
        sky_blue: Scale around `PrimaryColors.sky_blue`.
        teal: Scale around `PrimaryColors.teal`.
        amber: Scale around `PrimaryColors.amber`.
        violet: Scale around `PrimaryColors.violet`.
        rose: Scale around `PrimaryColors.rose`.
        green: Scale around `PrimaryColors.green`.
        default: `sky_blue`.
    """

    sky_blue = ['#bae6fd', '#7dd3fc', '#38bdf8', '#0ea5e9', '#0284c7', '#0369a1', '#075985']
    teal = ['#99f6e4', '#5eead4', '#2dd4bf', '#14b8a6', '#0d9488', '#0f766e', '#115e59']
    amber = ['#fde68a', '#fcd34d', '#fbbf24', '#f59e0b', '#d97706', '#b45309', '#92400e']
    violet = ['#ddd6fe', '#c4b5fd', '#a78bfa', '#8b5cf6', '#7c3aed', '#6d28d9', '#5b21b6']
    rose = ['#fecaca', '#f87171', '#ef4444', '#dc2626', '#b91c1c', '#991b1b', '#7f1d1d']
    green = ['#bbf7d0', '#86efac', '#4ade80', '#22c55e', '#16a34a', '#15803d', '#166534']
    default = sky_blue

DarkGreyColors

Bases: ConstantsIterable

Greys of the dark theme.

Attributes:

Name Type Description
background

Paper and plot background.

gridlines

Grid lines.

borders

Axis lines and zero lines.

text

Font color.

Source code in src/mesqual/utils/theme.py
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class DarkGreyColors(ConstantsIterable):
    """Greys of the dark theme.

    Attributes:
        background: Paper and plot background.
        gridlines: Grid lines.
        borders: Axis lines and zero lines.
        text: Font color.
    """

    background = '#111827'
    gridlines = '#374151'
    borders = '#4b5563'
    text = '#d1d5db'

LightGreyColors

Bases: ConstantsIterable

Greys of the light theme.

Attributes:

Name Type Description
background

Plot background.

paper

Paper background.

gridlines

Grid lines.

borders

Axis lines and zero lines.

text

Font color.

Source code in src/mesqual/utils/theme.py
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class LightGreyColors(ConstantsIterable):
    """Greys of the light theme.

    Attributes:
        background: Plot background.
        paper: Paper background.
        gridlines: Grid lines.
        borders: Axis lines and zero lines.
        text: Font color.
    """

    background = '#f8f9fa'
    paper = '#ffffff'
    gridlines = '#e9ecef'
    borders = '#ced4da'
    text = '#343a40'

DivergingColors

Bases: ConstantsIterable

Diverging color scales: one sequential scale reversed, followed by another one.

Attributes:

Name Type Description
teal_amber

Teal from dark to light, then amber from light to dark.

violet_green

Violet from dark to light, then green from light to dark.

default

teal_amber.

Source code in src/mesqual/utils/theme.py
82
83
84
85
86
87
88
89
90
91
92
93
class DivergingColors(ConstantsIterable):
    """Diverging color scales: one sequential scale reversed, followed by another one.

    Attributes:
        teal_amber: Teal from dark to light, then amber from light to dark.
        violet_green: Violet from dark to light, then green from light to dark.
        default: `teal_amber`.
    """

    teal_amber = SequentialColors.teal[::-1] + SequentialColors.amber
    violet_green = SequentialColors.violet[::-1] + SequentialColors.green
    default = teal_amber

CyclicalColors

Bases: ConstantsIterable

Cyclical color scales. The theme defines none.

Attributes:

Name Type Description
default

None.

Source code in src/mesqual/utils/theme.py
 96
 97
 98
 99
100
101
102
103
class CyclicalColors(ConstantsIterable):
    """Cyclical color scales. The theme defines none.

    Attributes:
        default: `None`.
    """

    default = None

QualitativeColors

Bases: ConstantsIterable

Colors for categories.

Attributes:

Name Type Description
default

Sky blue, teal, amber, violet, green and rose from PrimaryColors. The colorway of plotly_theme_dark and plotly_theme_light.

Source code in src/mesqual/utils/theme.py
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
class QualitativeColors(ConstantsIterable):
    """Colors for categories.

    Attributes:
        default: Sky blue, teal, amber, violet, green and rose from
            `PrimaryColors`. The colorway of `plotly_theme_dark` and
            `plotly_theme_light`.
    """

    default = [
        PrimaryColors.sky_blue,
        PrimaryColors.teal,
        PrimaryColors.amber,
        PrimaryColors.violet,
        PrimaryColors.green,
        PrimaryColors.rose,
    ]

ColorPalette

All color groups of the mesqual theme. The module constant colors is this class.

Attributes:

Name Type Description
primary

PrimaryColors.

greys_light

LightGreyColors.

greys_dark

DarkGreyColors.

sequential

SequentialColors.

diverging

DivergingColors.

cyclical

CyclicalColors.

qualitative

QualitativeColors.

Source code in src/mesqual/utils/theme.py
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
class ColorPalette:
    """All color groups of the mesqual theme. The module constant `colors` is this class.

    Attributes:
        primary: `PrimaryColors`.
        greys_light: `LightGreyColors`.
        greys_dark: `DarkGreyColors`.
        sequential: `SequentialColors`.
        diverging: `DivergingColors`.
        cyclical: `CyclicalColors`.
        qualitative: `QualitativeColors`.
    """

    primary = PrimaryColors
    greys_light = LightGreyColors
    greys_dark = DarkGreyColors
    sequential = SequentialColors
    diverging = DivergingColors
    cyclical = CyclicalColors
    qualitative = QualitativeColors

str_to_bool

Conversion of strings and other values to bool.

any_to_bool

any_to_bool(value) -> bool

Convert a value to a bool: a string with str_to_bool, any other value by its truth value.

So None gives False, and NaN gives True.

Parameters:

Name Type Description Default
value Any

The value.

required
Source code in src/mesqual/utils/str_to_bool.py
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
def any_to_bool(value) -> bool:
    """Convert a value to a bool: a string with `str_to_bool`, any other value by its truth value.

    So `None` gives False, and NaN gives True.

    Args:
        value (Any): The value.
    """
    if isinstance(value, str):
        return str_to_bool(value)
    elif value:
        return True
    return False

str_to_bool

str_to_bool(text: str) -> bool

Return False for false, f, 0, no, n, off or an empty string, in any case; True for any other string.

Source code in src/mesqual/utils/str_to_bool.py
19
20
21
def str_to_bool(text: str) -> bool:
    """Return False for `false`, `f`, `0`, `no`, `n`, `off` or an empty string, in any case; True for any other string."""
    return str(text).lower() not in ['false', 'f', '0', 'no', 'n', 'off', '']

pair_combiner

Names and tuples of pairs, for example of borders.

PairCombiner

Builds names and tuples of pairs: as given, reversed or sorted, for example 'C1 - C2' for a border from C1 to C2.

Parameters:

Name Type Description Default
separator str

Text between the two parts of a pair name.

' - '
Source code in src/mesqual/utils/pair_combiner.py
 4
 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
class PairCombiner:
    """Builds names and tuples of pairs: as given, reversed or sorted, for example `'C1 - C2'` for a border from C1 to C2.

    Args:
        separator (str): Text between the two parts of a pair name.
    """

    def __init__(self, separator=' - '):
        self.separator = separator

    def get_combo_as_str(self, a: str, b: str) -> str:
        """Return `a` and `b` joined by the separator, for example `'C1 - C2'`."""
        return self.separator.join([a, b])

    def get_combo_as_tuple(self, a: str, b: str) -> tuple[str, str]:
        """Return `(a, b)`."""
        return a, b

    def get_opposite_combo_as_str(self, a: str, b: str) -> str:
        """Return `b` and `a` joined by the separator, for example `'C2 - C1'` for `a='C1'`."""
        return self.separator.join([b, a])

    def get_opposite_combo_as_tuple(self, a: str, b: str) -> tuple[str, str]:
        """Return `(b, a)`."""
        return b, a

    def get_sorted_combo_as_str(self, a: str, b: str) -> str:
        """Return `a` and `b` in sorted order joined by the separator, so both orders give the same name."""
        return self.separator.join(sorted([b, a]))

    def get_sorted_combo_as_tuple(self, a: str, b: str) -> tuple[str, str]:
        """Return `a` and `b` as a tuple in sorted order."""
        return tuple(sorted([b, a]))

get_combo_as_str

get_combo_as_str(a: str, b: str) -> str

Return a and b joined by the separator, for example 'C1 - C2'.

Source code in src/mesqual/utils/pair_combiner.py
14
15
16
def get_combo_as_str(self, a: str, b: str) -> str:
    """Return `a` and `b` joined by the separator, for example `'C1 - C2'`."""
    return self.separator.join([a, b])

get_combo_as_tuple

get_combo_as_tuple(a: str, b: str) -> tuple[str, str]

Return (a, b).

Source code in src/mesqual/utils/pair_combiner.py
18
19
20
def get_combo_as_tuple(self, a: str, b: str) -> tuple[str, str]:
    """Return `(a, b)`."""
    return a, b

get_opposite_combo_as_str

get_opposite_combo_as_str(a: str, b: str) -> str

Return b and a joined by the separator, for example 'C2 - C1' for a='C1'.

Source code in src/mesqual/utils/pair_combiner.py
22
23
24
def get_opposite_combo_as_str(self, a: str, b: str) -> str:
    """Return `b` and `a` joined by the separator, for example `'C2 - C1'` for `a='C1'`."""
    return self.separator.join([b, a])

get_opposite_combo_as_tuple

get_opposite_combo_as_tuple(a: str, b: str) -> tuple[str, str]

Return (b, a).

Source code in src/mesqual/utils/pair_combiner.py
26
27
28
def get_opposite_combo_as_tuple(self, a: str, b: str) -> tuple[str, str]:
    """Return `(b, a)`."""
    return b, a

get_sorted_combo_as_str

get_sorted_combo_as_str(a: str, b: str) -> str

Return a and b in sorted order joined by the separator, so both orders give the same name.

Source code in src/mesqual/utils/pair_combiner.py
30
31
32
def get_sorted_combo_as_str(self, a: str, b: str) -> str:
    """Return `a` and `b` in sorted order joined by the separator, so both orders give the same name."""
    return self.separator.join(sorted([b, a]))

get_sorted_combo_as_tuple

get_sorted_combo_as_tuple(a: str, b: str) -> tuple[str, str]

Return a and b as a tuple in sorted order.

Source code in src/mesqual/utils/pair_combiner.py
34
35
36
def get_sorted_combo_as_tuple(self, a: str, b: str) -> tuple[str, str]:
    """Return `a` and `b` as a tuple in sorted order."""
    return tuple(sorted([b, a]))

set_aggregations

Intersection and union of several iterables.

nested_intersection

nested_intersection(iterable_of_iterables: Iterable[Iterable[T]]) -> set[T]

Intersection of all iterables. An empty input gives an empty set. A generator input works.

Source code in src/mesqual/utils/set_aggregations.py
 8
 9
10
11
12
13
def nested_intersection(iterable_of_iterables: Iterable[Iterable[T]]) -> set[T]:
    """Intersection of all iterables. An empty input gives an empty set. A generator input works."""
    items = list(iterable_of_iterables)
    if not items:
        return set()
    return set(items[0]).intersection(*items[1:])

nested_union

nested_union(iterable_of_iterables: Iterable[Iterable[T]]) -> set[T]

Union of all iterables. An empty input gives an empty set. A generator input works.

Source code in src/mesqual/utils/set_aggregations.py
16
17
18
def nested_union(iterable_of_iterables: Iterable[Iterable[T]]) -> set[T]:
    """Union of all iterables. An empty input gives an empty set. A generator input works."""
    return set().union(*iterable_of_iterables)

intersect_dicts

The key/value pairs that several dicts have in common.

get_intersection_of_dicts

get_intersection_of_dicts(dict_list: Iterable[dict]) -> dict

Returns a dictionary with key/value pairs that all provided dictionaries have in common.

Source code in src/mesqual/utils/intersect_dicts.py
 6
 7
 8
 9
10
11
12
13
def get_intersection_of_dicts(dict_list: Iterable[Dict]) -> Dict:
    """Returns a dictionary with key/value pairs that all provided dictionaries have in common."""
    if not dict_list:
        return dict()
    set_list = [set(d.items()) for d in dict_list]
    common_items = set.intersection(*set_list)
    common_dict = dict(common_items)
    return common_dict

check_all_same

Check whether all items are the same object.

all_same_object

all_same_object(items: Iterable) -> bool

True if all items are the same object. An empty input gives True. A generator input works.

Source code in src/mesqual/utils/check_all_same.py
6
7
8
9
def all_same_object(items: Iterable) -> bool:
    """`True` if all items are the same object. An empty input gives `True`. A generator input works."""
    items = list(items)
    return all(x is items[0] for x in items)

common_base_key_finder

Base keys that appear with each of several tags.

CommonBaseKeyFinder

Find the base keys that appear with each of several association tags.

The base key of a key is the key without the tag. A tag can be anywhere in the key, not only at the end.

Examples:

>>> finder = CommonBaseKeyFinder('_from', '_to')
>>> keys = ['node_from', 'node_to', 'node_via', 'country_from', 'country_to', 'capacity']
>>> sorted(finder.get_keys_for_which_all_association_tags_appear(keys))
['country', 'node']
Source code in src/mesqual/utils/multi_key_utils/common_base_key_finder.py
 4
 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
class CommonBaseKeyFinder:
    """
    Find the base keys that appear with each of several association tags.

    The base key of a key is the key without the tag. A tag can be anywhere
    in the key, not only at the end.

    Examples:
        >>> finder = CommonBaseKeyFinder('_from', '_to')
        >>> keys = ['node_from', 'node_to', 'node_via', 'country_from', 'country_to', 'capacity']
        >>> sorted(finder.get_keys_for_which_all_association_tags_appear(keys))
        ['country', 'node']
    """

    def __init__(self, *association_tags: str):
        if not association_tags or len(association_tags) < 2:
            raise ValueError('Identifiers must be a list with at least two elements.')
        self._association_tags = association_tags

    def get_keys_for_which_all_association_tags_appear(self, keys: list[str]) -> list[str]:
        """Return the base keys that appear with each tag, in no fixed order.

        The base key of a key is the key with all occurrences of a tag
        removed. The tag can be anywhere in the key, so `'x_from_y'` gives
        the base key `'x_y'` for the tag `'_from'`.
        """
        base_key_sets = [set() for _ in self._association_tags]

        for name in keys:
            for i, association_tag in enumerate(self._association_tags):
                if association_tag in name:
                    base_key_sets[i].add(name.replace(association_tag, ''))

        common_base_keys = set.intersection(*base_key_sets)
        return list(common_base_keys)

get_keys_for_which_all_association_tags_appear

get_keys_for_which_all_association_tags_appear(keys: list[str]) -> list[str]

Return the base keys that appear with each tag, in no fixed order.

The base key of a key is the key with all occurrences of a tag removed. The tag can be anywhere in the key, so 'x_from_y' gives the base key 'x_y' for the tag '_from'.

Source code in src/mesqual/utils/multi_key_utils/common_base_key_finder.py
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
def get_keys_for_which_all_association_tags_appear(self, keys: list[str]) -> list[str]:
    """Return the base keys that appear with each tag, in no fixed order.

    The base key of a key is the key with all occurrences of a tag
    removed. The tag can be anywhere in the key, so `'x_from_y'` gives
    the base key `'x_y'` for the tag `'_from'`.
    """
    base_key_sets = [set() for _ in self._association_tags]

    for name in keys:
        for i, association_tag in enumerate(self._association_tags):
            if association_tag in name:
                base_key_sets[i].add(name.replace(association_tag, ''))

    common_base_keys = set.intersection(*base_key_sets)
    return list(common_base_keys)