getml.data.View

def check(self):
    """
    Checks whether the underlying data frame has been changed
    after the creation of the view.
    """
    last_change = self.last_change
    if last_change != self.__dict__["_initial_timestamp"]:
        logger.warning(
            "The data frame underlying view '"
            + self.name
            + "' was last changed at "
            + last_change
            + ", which was after the creation of the view. "
            + "This might lead to unexpected results. You might "
            + "want to recreate the view. (Views are lazily "
            + "evaluated, so recreating them is a very "
            + "inexpensive operation)."
        )

def drop(self, cols: Union[str, List[str]]) -> View:
    """Returns a new [`View`][getml.data.View] that has one or several columns removed.

    Args:
        cols:
            The names of the columns to be dropped.

    Returns:
            A new view with the specified columns removed.
    """
    if isinstance(cols, str):
        cols = [cols]

    if not _is_typed_list(cols, str):
        raise TypeError("'cols' must be a string or a list of strings.")

    return View(base=self, dropped=cols)

def ncols(self) -> int:
    """
    Number of columns in the current instance.

    Returns:
            Overall number of columns
    """
    return len(self.colnames)

def nrows(self, force: bool = False) -> Union[int, str]:
    """
    Returns the number of rows in the current instance.

    Args:
        force:
            If the number of rows is unknown,
            do you want to force the Engine to calculate it anyway?
            This is a relatively expensive operation, therefore
            you might not necessarily want this.

    Returns:
            The number of rows in the current instance.
    """

    self.refresh()

    cmd: Dict[str, Any] = {}

    cmd["type_"] = "View.get_nrows"
    cmd["name_"] = ""

    cmd["cols_"] = [self[cname].cmd for cname in self.colnames]
    cmd["force_"] = force

    with comm.send_and_get_socket(cmd) as sock:
        json_str = comm.recv_string(sock)

    if json_str[0] != "{":
        comm.handle_engine_exception(json_str)

    response = json.loads(json_str)

    if "recordsTotal" in response:
        return response["recordsTotal"]

    # ensure that we do not display "unknown" if the number of rows is
    # less than or equal to the maximum number of diplayed rows
    nrows_to_display = len(self[: _ViewFormatter.max_rows + 1])
    if nrows_to_display <= _ViewFormatter.max_rows:
        return nrows_to_display

    return "unknown"

def refresh(self) -> View:
    """Aligns meta-information of the current instance with the
    corresponding data frame in the getML Engine.

    Returns:
            Updated handle the underlying data frame in the getML
            Engine.

    """
    self._base = self.__dict__["_base"].refresh()
    return self

def to_arrow(self) -> pyarrow.Table:
    """Creates a `pyarrow.Table` from the view.

    Loads the underlying data from the getML Engine and constructs
    a `pyarrow.Table`.

    Returns:
            Pyarrow equivalent of the current instance including
            its underlying data.
    """
    return to_arrow(self)

def to_json(self) -> str:
    """Creates a JSON string from the current instance.

    Loads the underlying data from the getML Engine and constructs
    a JSON string.

    Returns:
            JSON string of the current instance including its
            underlying data.
    """
    return self.to_pandas().to_json()

def to_csv(
    self,
    fname: str,
    quotechar: str = '"',
    sep: str = ",",
    batch_size: int = 0,
    quoting_style: str = "needed",
):
    """
    Writes the underlying data into a newly created CSV file.

    Args:
        fname:
            The name of the CSV file.
            The ending ".csv" and an optional batch number will
            be added automatically.

        quotechar:
            The character used to wrap strings.

        sep:
            The character used for separating fields.

        batch_size:
            Maximum number of lines per file. Set to 0 to read
            the entire data frame into a single file.

        quoting_style (str):
            The quoting style to use. Delegated to pyarrow.

            The following values are accepted:
            - `"needed"` (default): only enclose values in quotes when needed.
            - `"all_valid"`: enclose all valid values in quotes; nulls are not
              quoted.
            - `"none"`: do not enclose any values in quotes; values containing
              special characters (such as quotes, cell delimiters or line
              endings) will raise an error.

    Deprecated:
       1.5: The `quotechar` parameter is deprecated.
    """

    if quotechar != '"':
        warnings.warn(
            "'quotechar' is deprecated, use 'quoting_style' instead.",
            DeprecationWarning,
        )

    to_csv(self, fname, sep, batch_size, quoting_style)

def to_db(self, table_name: str, conn: Optional[Connection] = None):
    """Writes the underlying data into a newly created table in the
    database.

    Args:
        table_name:
            Name of the table to be created.

            If a table of that name already exists, it will be
            replaced.

        conn:
            The database connection to be used.
            If you don't explicitly pass a connection,
            the Engine will use the default connection.
    """

    conn = conn or Connection()

    self.refresh()

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

    if not isinstance(conn, Connection):
        raise TypeError("'conn' must be a getml.database.Connection object or None")

    cmd: Dict[str, Any] = {}

    cmd["type_"] = "View.to_db"
    cmd["name_"] = ""

    cmd["view_"] = self._getml_deserialize()
    cmd["table_name_"] = table_name
    cmd["conn_id_"] = conn.conn_id

    comm.send(cmd)

def to_df(self, name) -> DataFrame:
    """Creates a [`DataFrame`][getml.DataFrame] from the view."""
    self.check()
    self = self.refresh()
    df = data.DataFrame(name)
    return df.read_view(self)

def to_pandas(self) -> pd.DataFrame:
    """Creates a `pandas.DataFrame` from the view.

    Loads the underlying data from the getML Engine and constructs
    a `pandas.DataFrame`.

    Returns:
            Pandas equivalent of the current instance including
            its underlying data.
    """
    return to_arrow(self).to_pandas()

def to_placeholder(self, name: Optional[str] = None) -> Placeholder:
    """Generates a [`Placeholder`][getml.data.Placeholder] from the
    current [`View`][getml.data.View].

    Args:
        name:
            The name of the placeholder. If no
            name is passed, then the name of the placeholder will
            be identical to the name of the current view.

    Returns:
            A placeholder with the same name as this data frame.


    """
    self.refresh()
    return Placeholder(name=name or self.name, roles=self.roles)

def to_parquet(
    self,
    fname: str,
    compression: Literal["brotli", "gzip", "lz4", "snappy", "zstd"] = "snappy",
):
    """
    Writes the underlying data into a newly created parquet file.

    Args:
        fname:
            The name of the parquet file.
            The ending ".parquet" will be added automatically.

        compression:
            The compression format to use.
            Supported values are "brotli", "gzip", "lz4", "snappy", "zstd"
    """
    to_parquet(self, fname, compression)

def to_pyspark(
    self, spark: pyspark.sql.SparkSession, name: Optional[str] = None
) -> pyspark.sql.DataFrame:
    """Creates a `pyspark.sql.DataFrame` from the current instance.

    Loads the underlying data from the getML Engine and constructs
    a `pyspark.sql.DataFrame`.

    Args:
        spark:
            The pyspark session in which you want to
            create the data frame.

        name:
            The name of the temporary view to be created on top
            of the `pyspark.sql.DataFrame`,
            with which it can be referred to
            in Spark SQL (refer to
            `pyspark.sql.DataFrame.createOrReplaceTempView`).
            If none is passed, then the name of this
            [`DataFrame`][getml.DataFrame] will be used.

    Returns:
            Pyspark equivalent of the current instance including
            its underlying data.

    """
    return _to_pyspark(self, name, spark)

def to_s3(
    self,
    bucket: str,
    key: str,
    region: str,
    sep: str = ",",
    batch_size: int = 50000,
):
    """
    Writes the underlying data into a newly created CSV file
    located in an S3 bucket.

    Note:
        S3 is not supported on Windows.

    Args:
        bucket:
            The bucket from which to read the files.

        key:
            The key in the S3 bucket in which you want to
            write the output. The ending ".csv" and an optional
            batch number will be added automatically.

        region:
            The region in which the bucket is located.

        sep:
            The character used for separating fields.

        batch_size:
            Maximum number of lines per file. Set to 0 to read
            the entire data frame into a single file.

    ??? example
        ```python
        getml.engine.set_s3_access_key_id("YOUR-ACCESS-KEY-ID")
        getml.engine.set_s3_secret_access_key("YOUR-SECRET-ACCESS-KEY")

        your_view.to_s3(
            bucket="your-bucket-name",
            key="filename-on-s3",
            region="us-east-2",
            sep=';'
        )
        ```
    """

    self.refresh()

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

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

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

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

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

    cmd: Dict[str, Any] = {}

    cmd["type_"] = "View.to_s3"
    cmd["name_"] = self.name

    cmd["view_"] = self._getml_deserialize()
    cmd["bucket_"] = bucket
    cmd["key_"] = key
    cmd["region_"] = region
    cmd["sep_"] = sep
    cmd["batch_size_"] = batch_size

    comm.send(cmd)

def where(
    self, index: Optional[Union[BooleanColumnView, FloatColumn, FloatColumnView]]
) -> View:
    """Extract a subset of rows.

    Creates a new [`View`][getml.data.View] as a
    subselection of the current instance.

    Args:
        index:
            Boolean column indicating the rows you want to select.

    Returns:
        A new view containing only the rows that satisfy the condition.

    ??? example
        Generate example data:
        ```python
        data = dict(
            fruit=["banana", "apple", "cherry", "cherry", "melon", "pineapple"],
            price=[2.4, 3.0, 1.2, 1.4, 3.4, 3.4],
            join_key=["0", "1", "2", "2", "3", "3"])

        fruits = getml.DataFrame.from_dict(data, name="fruits",
        roles={"categorical": ["fruit"], "join_key": ["join_key"], "numerical": ["price"]})

        fruits
        ```
        ```
        | join_key | fruit       | price     |
        | join key | categorical | numerical |
        --------------------------------------
        | 0        | banana      | 2.4       |
        | 1        | apple       | 3         |
        | 2        | cherry      | 1.2       |
        | 2        | cherry      | 1.4       |
        | 3        | melon       | 3.4       |
        | 3        | pineapple   | 3.4       |
        ```
        Apply where condition. This creates a new DataFrame called "cherries":

        ```python

        cherries = fruits.where(
            fruits["fruit"] == "cherry")

        cherries
        ```
        ```
        | join_key | fruit       | price     |
        | join key | categorical | numerical |
        --------------------------------------
        | 2        | cherry      | 1.2       |
        | 2        | cherry      | 1.4       |
        ```
    """
    return _where(self, index)

def with_column(
    self,
    col: Union[
        bool,
        str,
        float,
        int,
        np.datetime64,
        FloatColumn,
        FloatColumnView,
        StringColumn,
        StringColumnView,
        BooleanColumnView,
    ],
    name: str,
    role: Optional[Role] = None,
    unit: str = "",
    subroles: Optional[Union[Subrole, Iterable[str]]] = None,
    time_formats: Optional[List[str]] = None,
) -> View:
    """Returns a new [`View`][getml.data.View] that contains an additional column.

    Args:
        col:
            The column to be added.

        name:
            Name of the new column.

        role:
            Role of the new column. Must be from [`roles`][getml.data.roles].

        subroles:
            Subroles of the new column. Must be from [`subroles`][getml.data.subroles].

        unit:
            Unit of the column.

        time_formats:
            Formats to be used to parse the time stamps.

            This is only necessary, if an implicit conversion from
            a [`StringColumn`][getml.data.columns.StringColumn] to a time
            stamp is taking place.

            The formats are allowed to contain the following
            special characters:

            * %w - abbreviated weekday (Mon, Tue, ...)
            * %W - full weekday (Monday, Tuesday, ...)
            * %b - abbreviated month (Jan, Feb, ...)
            * %B - full month (January, February, ...)
            * %d - zero-padded day of month (01 .. 31)
            * %e - day of month (1 .. 31)
            * %f - space-padded day of month ( 1 .. 31)
            * %m - zero-padded month (01 .. 12)
            * %n - month (1 .. 12)
            * %o - space-padded month ( 1 .. 12)
            * %y - year without century (70)
            * %Y - year with century (1970)
            * %H - hour (00 .. 23)
            * %h - hour (00 .. 12)
            * %a - am/pm
            * %A - AM/PM
            * %M - minute (00 .. 59)
            * %S - second (00 .. 59)
            * %s - seconds and microseconds (equivalent to %S.%F)
            * %i - millisecond (000 .. 999)
            * %c - centisecond (0 .. 9)
            * %F - fractional seconds/microseconds (000000 - 999999)
            * %z - time zone differential in ISO 8601 format (Z or +NN.NN)
            * %Z - time zone differential in RFC format (GMT or +NNNN)
            * %% - percent sign

    Returns:
        A new view containing the additional column.
    """
    col, role, subroles = _with_column(
        col, name, role, subroles, unit, time_formats
    )
    return View(
        base=self,
        added={
            "col_": col,
            "name_": name,
            "role_": role,
            "subroles_": subroles,
            "unit_": unit,
        },
    )

def with_name(self, name: str) -> View:
    """Returns a new [`View`][getml.data.View] with a new name.

    Args:
        name (str):
            The name of the new view.

    Returns:
        A new view with the new name.
    """
    return View(base=self, name=name)

def with_role(
    self,
    names: Union[str, List[str]],
    role: str,
    time_formats: Optional[List[str]] = None,
) -> View:
    """Returns a new [`View`][getml.data.View] with modified roles.

    When switching from a role based on type float to a role based on type
    string or vice verse, an implicit type conversion will be conducted.
    The `time_formats` argument is used to interpret time
    format string: `annotating_roles_time_stamp`. For more information on
    roles, please refer to the [User Guide][annotating-data].

    Args:
        names:
            The name or names of the column.

        role:
            The role to be assigned.

        time_formats:
            Formats to be used to parse the time stamps.
            This is only necessary, if an implicit conversion from a StringColumn to
            a time stamp is taking place.

    Returns:
        A new view with the modified roles.
    """
    return _with_role(self, names, role, time_formats)

def with_subroles(
    self,
    names: Union[str, List[str]],
    subroles: Union[Subrole, Iterable[str]],
    append: bool = True,
) -> View:
    """Returns a new view with one or several new subroles on one or more columns.

    Args:
        names:
            The name or names of the column.

        subroles:
            The subroles to be assigned.

        append:
            Whether you want to append the
            new subroles to the existing subroles.

    Returns:
        A new view with the modified subroles.
    """
    return _with_subroles(self, names, subroles, append)

def with_unit(
    self, names: Union[str, List[str]], unit: str, comparison_only: bool = False
) -> View:
    """Returns a view that contains a new unit on one or more columns.

    Args:
        names:
            The name or names of the column.

        unit:
            The unit to be assigned.

        comparison_only:
            Whether you want the column to
            be used for comparison only. This means that the column can
            only be used in comparison to other columns of the same unit.

            An example might be a bank account number: The number in itself
            is hardly interesting, but it might be useful to know how often
            we have seen that same bank account number in another table.

            If True, this will append ", comparison only" to the unit.
            The feature learning algorithms and the feature selectors will
            interpret this accordingly.

    Returns:
        A new view with the modified unit.
    """
    return _with_unit(self, names, unit, comparison_only)