getml.pipeline.Tables

Tables(
    targets: Sequence[str],
    columns: Columns,
    data: Optional[Sequence[Table]] = None,
)

This container holds a pipeline's tables. These tables are build from the columns for which importances can be calculated. The motivation behind this container is to determine which tables are more important than others.

Tables can be accessed by name, index or with a NumPy array. The container supports slicing and can be sorted and filtered. Further, the container holds global methods to request tables' importances.

PARAMETER	DESCRIPTION
targets	The targets associated with the pipeline. TYPE: Sequence[str]
columns	The columns with which the tables are built. TYPE: Columns
data	A list of Table objects. TYPE: Optional[Sequence[Table]] DEFAULT: None

Note

The container is an iterable. So, in addition to filter you can also use python list comprehensions for filtering.

Example

all_my_tables = my_pipeline.tables
first_table = my_pipeline.tables[0]
all_but_last_10_tables = my_pipeline.tables[:-10]
important_tables = [table for table in my_pipeline.tables if table.importance > 0.1]
names, importances = my_pipeline.tables.importances()

Source code in getml/pipeline/tables.py

def __init__(
    self,
    targets: Sequence[str],
    columns: Columns,
    data: Optional[Sequence[Table]] = None,
) -> None:
    self._targets = targets
    self._columns = columns

    if data is not None:
        self.data = data

    else:
        self._load_tables()

    if not (targets and columns) and not data:
        raise ValueError(
            "Missing required arguments. Either provide `targets` & "
            "`columns` or else provide `data`."
        )

names property

names: List[str]

Holds the names of a Pipeline's tables.

RETURNS	DESCRIPTION
List[str]	List containing the names.

Note

The order corresponds to the current sorting of the container.

targets property

targets: List[str]

Holds the targets of a Pipeline's tables.

RETURNS	DESCRIPTION
List[str]	List containing the names.

Note

The order corresponds to the current sorting of the container.

filter

filter(conditional: Callable[[Table], bool]) -> Tables

Filters the tables container.

PARAMETER	DESCRIPTION
conditional	A callable that evaluates to a boolean for a given item. TYPE: Callable[[Table], bool]

RETURNS	DESCRIPTION
Tables	A container of filtered tables.

Example

important_tables = my_pipeline.table.filter(lambda table: table.importance > 0.1)
peripheral_tables = my_pipeline.tables.filter(lambda table: table.marker == "[PERIPHERAL]")

Source code in getml/pipeline/tables.py

def filter(self, conditional: Callable[[Table], bool]) -> Tables:
    """
    Filters the tables container.

    Args:
        conditional:
            A callable that evaluates to a boolean for a given item.

    Returns:
            A container of filtered tables.

    ??? example
        ```python
        important_tables = my_pipeline.table.filter(lambda table: table.importance > 0.1)
        peripheral_tables = my_pipeline.tables.filter(lambda table: table.marker == "[PERIPHERAL]")
        ```
    """
    tables_filtered = [table for table in self.data if conditional(table)]
    return self._make_tables(tables_filtered)

importances

importances(
    target_num: int = 0, sort: bool = True
) -> Tuple[NDArray[str_], NDArray[float_]]

Returns the importances of tables.

Table importances are calculated by summing up the importances of the columns belonging to the tables. Each column is assigned an importance value that measures its contribution to the predictive performance. For each target, the importances add up to 1.

PARAMETER	DESCRIPTION
target_num	Indicates for which target you want to view the importances. (Pipelines can have more than one target.) TYPE: int DEFAULT: 0
sort	Whether you want the results to be sorted. TYPE: bool DEFAULT: True

RETURNS	DESCRIPTION
NDArray[str_]	The first array contains the names of the tables.
NDArray[float_]	The second array contains their importances. By definition, all importances add up to 1.

Source code in getml/pipeline/tables.py

def importances(
    self, target_num: int = 0, sort: bool = True
) -> Tuple[NDArray[np.str_], NDArray[np.float_]]:
    """
    Returns the importances of tables.

    Table importances are calculated by summing up the importances of the
    columns belonging to the tables. Each column is assigned an importance
    value that measures its contribution to the predictive performance. For
    each target, the importances add up to 1.

    Args:
        target_num:
            Indicates for which target you want to view the
            importances. (Pipelines can have more than one target.)

        sort:
            Whether you want the results to be sorted.

    Returns:
        The first array contains the names of the tables.
        The second array contains their importances. By definition, all importances add up to 1.
    """

    target_name = self._targets[target_num]

    names = np.empty(0, dtype=str)
    importances = np.empty(0, dtype=float)

    for table in self.data:
        if table.target == target_name:
            names = np.append(names, table.name)
            importances = np.append(importances, table.importance)

    if not sort:
        return names, importances

    indices = np.argsort(importances)[::-1]

    return (names[indices], importances[indices])

sort

sort(
    by: Optional[str] = None,
    key: Optional[Callable[[Table], Any]] = None,
    descending: Optional[bool] = None,
) -> Tables

Sorts the Tables container. If no arguments are provided the container is sorted by target and name.

PARAMETER	DESCRIPTION
by	The name of field to sort by. Possible fields: - name(s) - importances(s) TYPE: Optional[str] DEFAULT: None
key	A callable that evaluates to a sort key for a given item. TYPE: Optional[Callable[[Table], Any]] DEFAULT: None
descending	Whether to sort in descending order. TYPE: Optional[bool] DEFAULT: None

RETURNS	DESCRIPTION
Tables	A container of sorted tables.

Example

by_importance = my_pipeline.tables.sort(key=lambda table: table.importance)

Source code in getml/pipeline/tables.py

def sort(
    self,
    by: Optional[str] = None,
    key: Optional[Callable[[Table], Any]] = None,
    descending: Optional[bool] = None,
) -> Tables:
    """
    Sorts the Tables container. If no arguments are provided the
    container is sorted by target and name.

    Args:
        by:
            The name of field to sort by. Possible fields:
                - name(s)
                - importances(s)
        key:
            A callable that evaluates to a sort key for a given item.
        descending:
            Whether to sort in descending order.

    Returns:
            A container of sorted tables.

    ??? example
        ```python
        by_importance = my_pipeline.tables.sort(key=lambda table: table.importance)
        ```
    """

    reverse = False if descending is None else descending

    if (by is not None) and (key is not None):
        raise ValueError("Only one of `by` and `key` can be provided.")

    if key is not None:
        tables_sorted = sorted(self.data, key=key, reverse=reverse)
        return self._make_tables(tables_sorted)

    if by is None:
        tables_sorted = sorted(
            self.data, key=lambda table: table.name, reverse=reverse
        )
        tables_sorted.sort(key=lambda table: table.target)
        return self._make_tables(tables_sorted)

    if re.match(pattern="names?$", string=by):
        tables_sorted = sorted(
            self.data, key=lambda table: table.name, reverse=reverse
        )
        return self._make_tables(tables_sorted)

    if re.match(pattern="importances?$", string=by):
        reverse = True if descending is None else descending
        tables_sorted = sorted(
            self.data, key=lambda table: table.importance, reverse=reverse
        )
        return self._make_tables(tables_sorted)

    raise ValueError(f"Cannot sort by: {by}.")

to_pandas

to_pandas() -> DataFrame

Returns all information related to the tables in a pandas DataFrame.

RETURNS	DESCRIPTION
DataFrame	A pandas DataFrame containing the tables' names, importances, targets and markers.

Source code in getml/pipeline/tables.py

def to_pandas(self) -> pd.DataFrame:
    """
    Returns all information related to the tables in a pandas DataFrame.

    Returns:
        A pandas DataFrame containing the tables' names, importances, targets and markers.
    """

    data_frame = pd.DataFrame()

    for i, table in enumerate(self.data):
        data_frame.loc[i, "name"] = table.name
        data_frame.loc[i, "importance"] = table.importance
        data_frame.loc[i, "target"] = table.target
        data_frame.loc[i, "marker"] = table.marker

    return data_frame