getml.pipeline.Columns

def filter(self, conditional: Callable[[Column], bool]) -> Columns:
    """
    Filters the columns container.

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

    Returns:
        A container of filtered Columns.

    ??? example
        ```python
        important_columns = my_pipeline.columns.filter(lambda column: column.importance > 0.1)
        peripheral_columns = my_pipeline.columns.filter(lambda column: column.marker == "[PERIPHERAL]")
        ```
    """
    columns_filtered = [column for column in self.data if conditional(column)]
    return self._make_columns(columns_filtered)

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

    Column importances extend the idea of column importances
    to the columns originally inserted into the pipeline.
    Each column is assigned an importance value that measures
    its contribution to the predictive performance. All
    columns importances add up to 1.

    The importances can be calculated for columns with
    [`roles`][getml.data.roles] such as [`categorical`][getml.data.roles.categorical],
    [`numerical`][getml.data.roles.numerical] and [`text`][getml.data.roles.text].
    The rest of the columns with roles [`time_stamp`][getml.data.roles.time_stamp],
    [`join_key`][getml.data.roles.join_key], [`target`][getml.data.roles.target],
    [`unused_float`][getml.data.roles.unused_float] and
    [`unused_string`][getml.data.roles.unused_string] can not have importance of course.

    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 columns.
        The second array contains their importances. By definition, all importances add up to 1.
    """

    # ------------------------------------------------------------

    descriptions, importances = self._get_column_importances(
        target_num=target_num, sort=sort
    )

    # ------------------------------------------------------------

    names = np.asarray(
        [d["marker_"] + " " + d["table_"] + "." + d["name_"] for d in descriptions]
    )

    # ------------------------------------------------------------

    return names, importances

def select(
    self,
    container: Union[Container, StarSchema, TimeSeries],
    share_selected_columns: float = 0.5,
) -> Container:
    """
    Returns a new data container with all insufficiently important columns dropped.

    Args:
        container:
            The container containing the data you want to use.

        share_selected_columns: The share of columns
            to keep. Must be between 0.0 and 1.0.

    Returns:
        A new container with the columns dropped.
    """

    # ------------------------------------------------------------

    if isinstance(container, (StarSchema, TimeSeries)):
        data = self.select(
            container.container, share_selected_columns=share_selected_columns
        )
        new_container = deepcopy(container)
        new_container._container = data
        return new_container

    # ------------------------------------------------------------

    if not isinstance(container, Container):
        raise TypeError(
            "'container' must be a getml.data.Container, "
            + "a getml.data.StarSchema or a getml.data.TimeSeries"
        )

    if not isinstance(share_selected_columns, numbers.Real):
        raise TypeError("'share_selected_columns' must be a real number!")

    if share_selected_columns < 0.0 or share_selected_columns > 1.0:
        raise ValueError("'share_selected_columns' must be between 0 and 1!")

    # ------------------------------------------------------------

    descriptions, _ = self._get_column_importances(target_num=-1, sort=True)

    # ------------------------------------------------------------

    num_keep = int(np.ceil(share_selected_columns * len(descriptions)))

    keep_columns = descriptions[:num_keep]

    # ------------------------------------------------------------

    subsets = {
        k: _drop(v, keep_columns, k, POPULATION)
        for (k, v) in container.subsets.items()
    }

    peripheral = {
        k: _drop(v, keep_columns, k, PERIPHERAL)
        for (k, v) in container.peripheral.items()
    }

    # ------------------------------------------------------------

    new_container = Container(**subsets)
    new_container.add(**peripheral)
    new_container.freeze()

    # ------------------------------------------------------------

    return new_container

def sort(
    self,
    by: Optional[str] = None,
    key: Optional[Callable[[Column], Any]] = None,
    descending: Optional[bool] = None,
) -> Columns:
    """
    Sorts the Columns 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)
                - table(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 columns.

    ??? example
        ```python
        by_importance = my_pipeline.columns.sort(key=lambda column: column.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:
        columns_sorted = sorted(self.data, key=key, reverse=reverse)
        return self._make_columns(columns_sorted)

    if by is None:
        columns_sorted = sorted(
            self.data, key=lambda column: column.name, reverse=reverse
        )
        columns_sorted.sort(key=lambda column: column.target)
        return self._make_columns(columns_sorted)

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

    if re.match(pattern="tables?$", string=by):
        columns_sorted = sorted(
            self.data,
            key=lambda column: column.table,
        )
        return self._make_columns(columns_sorted)

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

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

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

    names, markers, tables, importances, targets = (
        self._pivot(field)
        for field in ["name", "marker", "table", "importance", "target"]
    )

    data_frame = pd.DataFrame(index=np.arange(len(self.data)))

    data_frame["name"] = names

    data_frame["marker"] = markers

    data_frame["table"] = tables

    data_frame["importance"] = importances

    data_frame["target"] = targets

    return data_frame