Skip to content

Common

This is the reference to the functions contained in common. For now, they are all accesible directly through machine-learning-datasets and you don't need to use the common namespace.

Common Utility Functions

BaseAIF360DSProtocol

Bases: Protocol

Protocol for AIF360 Datasets

Source code in machine_learning_datasets/common.py 
30
31
32
33
class BaseAIF360DSProtocol(Protocol):
    """Protocol for AIF360 Datasets"""
    def validate_dataset(self) -> Any:
        """Validate the AIF360 dataset"""

validate_dataset()

Validate the AIF360 dataset

Source code in machine_learning_datasets/common.py 
32
33
def validate_dataset(self) -> Any:
    """Validate the AIF360 dataset"""

BaseAIF360MetricProtocol

Bases: Protocol

Protocol for AIF360 Metrics

Source code in machine_learning_datasets/common.py 
35
36
37
38
class BaseAIF360MetricProtocol(Protocol):
    """Protocol for AIF360 Metrics"""
    def num_instances(self, privileged:Optional[bool]=None) -> int:
        """Count the number of priviledged instances"""

num_instances(privileged=None)

Count the number of priviledged instances

Source code in machine_learning_datasets/common.py 
37
38
def num_instances(self, privileged:Optional[bool]=None) -> int:
    """Count the number of priviledged instances"""

BaseAlibiExplanationProtocol

Bases: Protocol

Protocol for Alibi Explanations

Source code in machine_learning_datasets/common.py 
40
41
42
43
class BaseAlibiExplanationProtocol(Protocol):
    """Protocol for Alibi Explanations"""
    def to_json(self) -> str:
        """Convert the Alibi explanation to JSON format"""

to_json()

Convert the Alibi explanation to JSON format

Source code in machine_learning_datasets/common.py 
42
43
def to_json(self) -> str:
    """Convert the Alibi explanation to JSON format"""

BaseModelProtocol

Bases: Protocol

Protocol for Any Sklearn Compatible Models

Source code in machine_learning_datasets/common.py 
17
18
19
20
class BaseModelProtocol(Protocol):
    """Protocol for Any Sklearn Compatible Models"""
    def predict(self, X:ArrayLike, **kwargs:Any) -> Any:
        """Predict with the fitted model"""

predict(X, **kwargs)

Predict with the fitted model

Source code in machine_learning_datasets/common.py 
19
20
def predict(self, X:ArrayLike, **kwargs:Any) -> Any:
    """Predict with the fitted model"""

BaseTransformerProtocol

Bases: Protocol

Protocol for Any Sklearn Compatible Scalers, Encoders & Transformers

Source code in machine_learning_datasets/common.py 
22
23
24
25
26
27
28
class BaseTransformerProtocol(Protocol):
    """Protocol for Any Sklearn Compatible Scalers, Encoders & Transformers"""
    def transform(self, X:ArrayLike, **kwargs:Any) -> Any:
        """Transform with the fitted transformer"""

    def inverse_transform(self, X:ArrayLike, **kwargs:Any) -> Any:
        """Inverse transform with the fitted transformer"""

inverse_transform(X, **kwargs)

Inverse transform with the fitted transformer

Source code in machine_learning_datasets/common.py 
27
28
def inverse_transform(self, X:ArrayLike, **kwargs:Any) -> Any:
    """Inverse transform with the fitted transformer"""

transform(X, **kwargs)

Transform with the fitted transformer

Source code in machine_learning_datasets/common.py 
24
25
def transform(self, X:ArrayLike, **kwargs:Any) -> Any:
    """Transform with the fitted transformer"""

plot_polar(df, r, theta, name=None, show=True)

Plots a polar line chart using Plotly Express.

Parameters:

Name Type Description Default
df DataFrame

The DataFrame containing the data.

 required
r Union[str, int, ArrayLike]

The column name or index of the radial coordinate.

 required
theta Union[str, int, ArrayLike]

The column name or index of the angular coordinate.

 required
name Optional[str]

The title of the chart. Defaults to None.

 None
show Optional[bool]

Whether to display the chart. Defaults to True.

 True

Returns:

Type Description
Optional[Figure]

Optional[Figure]: The Plotly Figure object if show is False, otherwise None.

Raises:

Type Description
ModuleNotFoundError

If plotly or kaleido is not installed.
Example

plot_polar(df, 'r', 'theta', name='Polar Chart', show=True)

Source code in machine_learning_datasets/common.py 
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def plot_polar(
        df:pd.DataFrame,
        r:Union[str, int, ArrayLike],
        theta:Union[str, int, ArrayLike],
        name:Optional[str] = None,
        show:Optional[bool] = True
    ) -> Optional[Figure]:
    """Plots a polar line chart using Plotly Express.

    Args:
        df (pd.DataFrame): The DataFrame containing the data.
        r (Union[str, int, ArrayLike]): The column name or index of the radial coordinate.
        theta (Union[str, int, ArrayLike]): The column name or index of the angular coordinate.
        name (Optional[str], optional): The title of the chart. Defaults to None.
        show (Optional[bool], optional): Whether to display the chart. Defaults to True.

    Returns:
        Optional[Figure]: The Plotly Figure object if show is False, otherwise None.

    Raises:
        ModuleNotFoundError: If `plotly` or `kaleido` is not installed.

    Example:
        plot_polar(df, 'r', 'theta', name='Polar Chart', show=True)
    """
    try:
        import plotly.express as px
    except ModuleNotFoundError as exc:
        raise ModuleNotFoundError("`plotly` must be installed to execute this function") from exc
    fig = px.line_polar(df, r=r, theta=theta, line_close=True, title=name)
    fig.update_traces(fill='toself')

    if show:
        try:
            import kaleido
        except ModuleNotFoundError as exc:
            raise ModuleNotFoundError("`kaleido` must be installed to execute "
                                      "this function") from exc
        if name is None:
            name = 'default'

        name = name.lower()
        cwd = os.getcwd()
        img_path = os.path.join(cwd, f"{name}.png")
        fig.write_image(img_path)
        show_image(img_path, width=800)
    else:
        return fig

runcmd(cmd, verbose=False)

Runs a command in the shell and captures the output.

Parameters:

Name Type Description Default
cmd str

The command to be executed.

 required
verbose bool

If True, the output will be printed to the console. Defaults to False.

 False

Returns:

Type Description
Tuple[bool, str, int]

Tuple[bool, str, int]: A tuple containing the following elements: - error (bool): True if an error occurred during the execution of the command, False otherwise. - output (str): The output generated by the command. - numlines (int): The number of lines in the output.
Source code in machine_learning_datasets/common.py 
45
46
47
48
49
50
51
52
53
54
55
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
def runcmd(
        cmd:str,
        verbose:Optional[bool] = False
    ) -> Tuple[bool, str, int]:
    """Runs a command in the shell and captures the output.

    Args:
        cmd (str): The command to be executed.
        verbose (bool, optional): If True, the output will be printed to the console.
                                  Defaults to False.

    Returns:
        Tuple[bool, str, int]: A tuple containing the following elements:
            - error (bool): True if an error occurred during the execution of the command,
                            False otherwise.
            - output (str): The output generated by the command.
            - numlines (int): The number of lines in the output.
    """
    sproc = subprocess.Popen(cmd, shell=True, stdin=subprocess.PIPE,
                             stdout=subprocess.PIPE, stderr=subprocess.PIPE, )
    output = ''
    numlines = 0
    error = True
    while True:
        if error is True:
            line = sproc.stderr.readline().decode("utf-8")
            if line == '' and (sproc.poll() is None or sproc.poll() == 0):
                error = False
        if error is False:
            line = sproc.stdout.readline().decode("utf-8")
        if line == '' and sproc.poll() is not None:
            break
        if verbose:
            sys.stdout.write(line)
            sys.stdout.flush()
        output = output + line
        numlines = numlines + 1

    return error, output.strip(), numlines

show_image(path_to_image, width=None, height=None)

Displays an image in Jupyter Notebook.

Parameters:

Name Type Description Default
path_to_image str

The path to the image file.

 required
width Optional[int]

The width of the displayed image. Defaults to None.

 None
height Optional[int]

The height of the displayed image. Defaults to None.

 None

Raises:

Type Description
ModuleNotFoundError

If ipython module is not installed.

Raises:

Type Description
ValueError

If the extension of the image file is unknown.

Returns:

Type Description
None

None
Example

show_image('path/to/image.jpg', width=500, height=300)

Source code in machine_learning_datasets/common.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
def show_image(
        path_to_image:str,
        width:Optional[int] = None,
        height:Optional[int] = None
    ) -> None:
    """Displays an image in Jupyter Notebook.

    Args:
        path_to_image (str): The path to the image file.
        width (Optional[int]): The width of the displayed image. Defaults to None.
        height (Optional[int]): The height of the displayed image. Defaults to None.

    Raises:
        ModuleNotFoundError: If `ipython` module is not installed.

    Raises:
        ValueError: If the extension of the image file is unknown.

    Returns:
        None

    Example:
        show_image('path/to/image.jpg', width=500, height=300)
    """
    try:
        from IPython.display import display, HTML #Image,
        from base64 import b64encode
    except ModuleNotFoundError as exc:
        raise ModuleNotFoundError("`ipython` must be installed to execute this function") from exc

    mime_type = None

    # More MIME types:
    # https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types
    if path_to_image.endswith('.jpg') or path_to_image.endswith('.jpeg'):
        mime_type = 'image/jpeg'
    elif path_to_image.endswith('.png'):
        mime_type = 'image/png'
    elif path_to_image.endswith('.gif'):
        mime_type = 'image/gif'
    else:
        raise ValueError(f'Unknown extension: {path_to_image}')

    img = open(path_to_image, 'rb').read()
    data_url = f'data:{mime_type};base64,' + b64encode(img).decode()

    width_str = f"width='{width:d}'" if width is not None else ''
    height_str = f"height='{height:d}'" if height is not None else ''

    display(HTML(f"<img src='{data_url}' {width_str}{height_str}>"))