getml.data

def arange(
    start: Union[numbers.Real, float] = 0.0,
    stop: Optional[Union[numbers.Real, float]] = None,
    step: Union[numbers.Real, float] = 1.0,
):
    """
    Returns evenly spaced variables, within a given interval.

    Args:
        start:
            The beginning of the interval. Defaults to 0.

        stop:
            The end of the interval.

        step:
            The step taken. Defaults to 1.
    """
    if stop is None:
        stop = start
        start = 0.0

    if step is None:
        step = 1.0

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

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

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

    col = FloatColumnView(
        operator="arange",
        operand1=None,
        operand2=None,
    )

    col.cmd["start_"] = float(start)
    col.cmd["stop_"] = float(stop)
    col.cmd["step_"] = float(step)

    return col

def rowid() -> FloatColumnView:
    """
    Get the row numbers of the table.

    Returns:
            (numerical) column containing the row id, starting with 0
    """
    return FloatColumnView(operator="rowid", operand1=None, operand2=None)

def list_data_frames() -> Dict[str, List[str]]:
    """Lists all available data frames of the project.

    Returns:
        dict:
            Dict containing lists of strings representing the names of
            the data frames objects

            - 'in_memory'
                held in memory (RAM).
            - 'on_disk'
                stored on disk.

    ??? example
        ```python
        d, _ = getml.datasets.make_numerical()
        getml.data.list_data_frames()
        d.save()
        getml.data.list_data_frames()
        ```

    """

    cmd: Dict[str, Any] = {}
    cmd["type_"] = "list_data_frames"
    cmd["name_"] = ""

    with comm.send_and_get_socket(cmd) as sock:
        msg = comm.recv_string(sock)
        if msg != "Success!":
            comm.handle_engine_exception(msg)
        json_str = comm.recv_string(sock)

    return json.loads(json_str)

def delete(name: str):
    """
    If a data frame named 'name' exists, it is deleted.

    Args:
        name:
            Name of the data frame.
    """

    if not isinstance(name, str):
        raise TypeError("'name' must be of type str")

    if exists(name):
        DataFrame(name).delete()

def exists(name: str):
    """
    Returns true if a data frame named 'name' exists.

    Args:
        name:
            Name of the data frame.
    """
    if not isinstance(name, str):
        raise TypeError("'name' must be of type str")

    all_df = list_data_frames()

    return name in (all_df["in_memory"] + all_df["on_disk"])

def load_data_frame(name: str) -> DataFrame:
    """Retrieves a [`DataFrame`][getml.DataFrame] handler of data in the
    getML Engine.

    A data frame object can be loaded regardless if it is held in
    memory or not. It only has to be present in the current project
    and thus listed in the output of
    [`list_data_frames`][getml.data.list_data_frames].

    Args:
        name:
            Name of the data frame.

    Returns:
            Handle the underlying data frame in the getML Engine.

    ??? example
        ```python
        d, _ = getml.datasets.make_numerical(population_name = 'test')
        d2 = getml.data.load_data_frame('test')
        ```
    """

    if not isinstance(name, str):
        raise TypeError("'name' must be of type str")

    data_frames_available = list_data_frames()

    if name in data_frames_available["in_memory"]:
        return DataFrame(name).refresh()

    if name in data_frames_available["on_disk"]:
        return DataFrame(name).load()

    raise ValueError(
        "No data frame holding the name '" + name + "' present on the getML Engine."
    )

def make_target_columns(base: Union[DataFrame, View], colname: str) -> View:
    """
    Returns a view containing binary target columns.

    getML expects binary target columns for classification problems. This
    helper function allows you to split up a column into such binary
    target columns.

    Args:
        base:
            The original view or data frame. `base` will remain unaffected
            by this function, instead you will get a view with the appropriate
            changes.

        colname: The column you would like to split. A column named
            `colname` should appear on `base`.

    Returns:
        A view containing binary target columns.
    """
    if not isinstance(
        base[colname], (FloatColumn, FloatColumnView, StringColumn, StringColumnView)
    ):
        raise TypeError(
            "'"
            + colname
            + "' must be a FloatColumn, a FloatColumnView, "
            + "a StringColumn or a StringColumnView."
        )

    unique_values = base[colname].unique()

    if len(unique_values) > 10:
        logger.warning(
            "You are splitting the column into more than 10 target "
            + "columns. This might take a long time to fit."
        )

    view = base

    for label in unique_values:
        col = (base[colname] == label).as_num()
        name = colname + "=" + label
        view = view.with_column(col=col, name=name, role=target)

    return view.drop(colname)

def to_placeholder(
    *args: Union[DataFrame, View, List[Union[DataFrame, View]]],
    **kwargs: Union[DataFrame, View, List[Union[DataFrame, View]]],
) -> List[Placeholder]:
    """
    Factory function for extracting placeholders from a
    [`DataFrame`][getml.DataFrame] or [`View`][getml.data.View].

    Args:
        args:
            The data frames or views you would like to convert to placeholders.

        kwargs:
            The data frames or views you would like to convert to placeholders.

    Returns:
        A list of placeholders.

    ??? example
        Suppose we wanted to create a [`DataModel`][getml.data.DataModel]:



            dm = getml.data.DataModel(
                population_train.to_placeholder("population")
            )

            # Add placeholders for the peripheral tables.
            dm.add(meta.to_placeholder("meta"))
            dm.add(order.to_placeholder("order"))
            dm.add(trans.to_placeholder("trans"))

        But this is a bit repetitive. So instead, we can do
        the following:
        ```python
        dm = getml.data.DataModel(
            population_train.to_placeholder("population")
        )

        # Add placeholders for the peripheral tables.
        dm.add(getml.data.to_placeholder(
            meta=meta, order=order, trans=trans))
        ```
    """

    def to_ph_list(list_or_elem, key=None):
        as_list = list_or_elem if isinstance(list_or_elem, list) else [list_or_elem]
        return [elem.to_placeholder(key) for elem in as_list]

    return [elem for item in args for elem in to_ph_list(item)] + [
        elem for (k, v) in kwargs.items() for elem in to_ph_list(v, k)
    ]