Source code for getml.data.view

# Copyright 2021 The SQLNet Company GmbH

# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:

# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.

# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
# DEALINGS IN THE SOFTWARE.

"""Contains the view."""

import json
import numbers
import os
from collections import namedtuple
from copy import deepcopy

import numpy as np
import pandas as pd  # type: ignore

import getml.communication as comm
from getml.database import Connection
from getml.log import logger
from getml.utilities.formatting import _ViewFormatter

from .columns import BooleanColumnView, FloatColumn, FloatColumnView, arange, rowid
from .helpers import (
    _is_typed_list,
    _make_default_slice,
    _to_arrow,
    _to_parquet,
    _to_pyspark,
    _with_column,
    _with_role,
    _with_subroles,
    _with_unit,
)
from .placeholder import Placeholder
from .roles import (
    categorical,
    join_key,
    numerical,
    target,
    text,
    time_stamp,
    unused_float,
    unused_string,
)
from .roles_obj import Roles

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


[docs]class View: """A view is a lazily evaluated, immutable representation of a :class:`~getml.DataFrame`. There are important differences between a :class:`~getml.DataFrame` and a view: - Views are lazily evaluated. That means that views do not contain any data themselves. Instead, they just refer to an underlying data frame. If the underlying data frame changes, so will the view (but such behavior will result in a warning). - Views are immutable. In-place operations on a view are not possible. Any operation on a view will result in a new view. - Views have no direct representation on the getML engine and therefore they do not need to have an identifying name. Args: base (:class:`~getml.DataFrame` or :class:`~getml.data.View`): A data frame or view used as the basis for this view. name (str): The name assigned to this view. subselection (:class:`~getml.data.columns.BooleanColumnView`, :class:`~getml.data.columns.FloatColumnView` or :class:`~getml.data.columns.FloatColumn`): Indicates which rows we would like to keep. added (dict): A dictionary that describes a new column that has been added to the view. dropped (List[str]): A list of columns that have been dropped. Examples: You hardly ever directly create views. Instead, it is more likely that you will encounter them as a result of some operation on a :class:`~getml.DataFrame`: .. code-block:: python # Creates a view on the first 100 lines view1 = data_frame[:100] # Creates a view without some columns. view2 = data_frame.drop(["col1", "col2"]) # Creates a view in which some roles are reassigned. view3 = data_frame.with_role(["col1", "col2"], getml.data.roles.categorical) A recommended pattern is to assign 'baseline roles' to your data frames and then using views to tweak them: .. code-block:: python # Assign baseline roles data_frame.set_role(["jk"], getml.data.roles.join_key) data_frame.set_role(["col1", "col2"], getml.data.roles.categorical) data_frame.set_role(["col3", "col4"], getml.data.roles.numerical) data_frame.set_role(["col5"], getml.data.roles.target) # Make the data frame immutable, so in-place operations are # no longer possible. data_frame.freeze() # Save the data frame. data_frame.save() # I suspect that col1 leads to overfitting, so I will drop it. view = data_frame.drop(["col1"]) # Insert the view into a container. container = getml.data.Container(...) container.add(some_alias=view) container.save() The advantage of using such a pattern is that it enables you to always completely retrace your entire pipeline without creating deep copies of the data frames whenever you have made a small change like the one in our example. Note that the pipeline will record which :class:`~getml.data.Container` you have used. """ # ------------------------------------------------------------ def __init__(self, base, name=None, subselection=None, added=None, dropped=None): self._added = added self._base = deepcopy(base) self._dropped = dropped or [] self._name = name self._subselection = subselection self._initial_timestamp = ( self._base._initial_timestamp if isinstance(self._base, View) else self._base.last_change ) self._base.refresh() # ------------------------------------------------------------ def _apply_subselection(self, col): if self._subselection is not None: return col[self._subselection] return col # ------------------------------------------------------------ def _collect_footer_data(self): footer = namedtuple("footer", ["n_rows", "n_cols", "type"]) n_rows = "unknown number of" if self.nrows() == "unknown" else self.nrows() return footer( n_rows=n_rows, n_cols=len(self.colnames), type="getml.data.View", ) # ------------------------------------------------------------ def _format(self): return _ViewFormatter(self) # ---------------------------------------------------------------- def __getattr__(self, name): try: return self[name] except KeyError: return super().__getattribute__(name) # ------------------------------------------------------------ def __getitem__(self, name): if isinstance( name, (numbers.Integral, slice, BooleanColumnView, FloatColumn, FloatColumnView), ): return self.where(index=name) if isinstance(name, list): not_in_colnames = set(name) - set(self.colnames) if not_in_colnames: raise KeyError(f"{list(not_in_colnames)} not found.") dropped = [col for col in self.colnames if col not in name] return View(base=self, dropped=dropped) if name in self.__dict__["_dropped"]: raise KeyError( "Cannot retrieve column '" + name + "'. It has been dropped." ) if ( self.__dict__["_added"] is not None and self.__dict__["_added"]["name_"] == name ): return self._apply_subselection( self.__dict__["_added"]["col_"] .with_subroles(self.__dict__["_added"]["subroles_"], append=False) .with_unit(self.__dict__["_added"]["unit_"]) ) return self._apply_subselection(self.__dict__["_base"][name]) # ---------------------------------------------------------------- def __len__(self): return self.nrows(force=True) # ------------------------------------------------------------ def _getml_deserialize(self): cmd = dict() cmd["type_"] = "View" if self._added is not None: added = deepcopy(self._added) col = deepcopy(added["col_"].cmd) col["last_change_"] = added["col_"].last_change added["col_"] = col cmd["added_"] = added if self._subselection is not None: subselection = deepcopy(self._subselection.cmd) subselection["last_change_"] = self.subselection.last_change cmd["subselection_"] = subselection cmd["base_"] = self._base._getml_deserialize() cmd["dropped_"] = self._dropped cmd["name_"] = self.name cmd["last_change_"] = self.last_change return cmd # ------------------------------------------------------------ def _modify_colnames(self, base_names, role): remove_dropped = [name for name in base_names if name not in self._dropped] if self._added is not None and self._added["role_"] != role: return [name for name in remove_dropped if name != self._added["name_"]] if ( self._added is not None and self._added["role_"] == role and self._added["name_"] not in remove_dropped ): return remove_dropped + [self._added["name_"]] return remove_dropped # ------------------------------------------------------------ def __repr__(self): formatted = self._format() footer = self._collect_footer_data() return formatted._render_string(footer=footer) # ---------------------------------------------------------------- def _repr_html_(self): formatted = self._format() footer = self._collect_footer_data() return formatted._render_html(footer=footer) # ------------------------------------------------------------ @property def added(self): """ The column that has been added to the view. """ return deepcopy(self._added) # ------------------------------------------------------------ @property def base(self): """ The basis on which the view is created. Must be a :class:`~getml.DataFrame` or a :class:`~getml.data.View`. """ return deepcopy(self._base) # ------------------------------------------------------------ @property def _categorical_names(self): return self._modify_colnames(self._base._categorical_names, categorical) # ------------------------------------------------------------
[docs] 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)." )
# ------------------------------------------------------------ @property def colnames(self): """ List of the names of all columns. Returns: List[str]: List of the names of all columns. """ return ( self._time_stamp_names + self._join_key_names + self._target_names + self._categorical_names + self._numerical_names + self._text_names + self._unused_names ) # ------------------------------------------------------------ @property def columns(self): """ Alias for :meth:`~getml.View.colnames`. Returns: List[str]: List of the names of all columns. """ return self.colnames # ------------------------------------------------------------
[docs] def drop(self, cols): """Returns a new :class:`~getml.data.View` that has one or several columns removed. Args: cols (str or List[str]): The names of the columns to be dropped. """ 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)
# ------------------------------------------------------------ @property def dropped(self): """ The names of the columns that has been dropped. """ return deepcopy(self._dropped) # ------------------------------------------------------------ @property def last_change(self): """ A string describing the last time this data frame has been changed. """ return self.__dict__["_base"].last_change # ------------------------------------------------------------ @property def _join_key_names(self): return self._modify_colnames(self._base._join_key_names, join_key) # ------------------------------------------------------------ @property def name(self): """ The name of the view. If no name is explicitly set, the name will be identical to the name of the base. """ if self.__dict__["_name"] is None: return self.__dict__["_base"].name return deepcopy(self.__dict__["_name"]) # ------------------------------------------------------------
[docs] def ncols(self): """ Number of columns in the current instance. Returns: int: Overall number of columns """ return len(self.colnames)
# ------------------------------------------------------------
[docs] def nrows(self, force=False): """ Returns the number of rows in the current instance. Args: force (bool, optional): 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. """ # ------------------------------------------------------------ self.refresh() # ------------------------------------------------------------ cmd = dict() cmd["type_"] = "View.get_nrows" cmd["name_"] = "" cmd["cols_"] = [self[cname].cmd for cname in self.colnames] cmd["force_"] = force sock = comm.send_and_get_socket(cmd) # ------------------------------------------------------------ json_str = comm.recv_string(sock) sock.close() if json_str[0] != "{": comm.engine_exception_handler(json_str) # ------------------------------------------------------------ result = json.loads(json_str) if "recordsTotal" in result: return int(result["recordsTotal"]) return "unknown"
# ------------------------------------------------------------ @property def _numerical_names(self): return self._modify_colnames(self._base._numerical_names, numerical) # --------------------------------------------------------------------------
[docs] def refresh(self): """Aligns meta-information of the current instance with the corresponding data frame in the getML engine. Returns: :class:`~getml.data.View`: Updated handle the underlying data frame in the getML engine. """ self._base = self.__dict__["_base"].refresh() return self
# ------------------------------------------------------------ @property def roles(self): """ The roles of the columns included in this View. """ return Roles( categorical=self._categorical_names, join_key=self._join_key_names, numerical=self._numerical_names, target=self._target_names, text=self._text_names, time_stamp=self._time_stamp_names, unused_float=self._unused_float_names, unused_string=self._unused_string_names, ) # ------------------------------------------------------------ @property def rowid(self): """ The rowids for this view. """ return rowid()[: len(self)] # ------------------------------------------------------------ @property def subselection(self): """ The subselection that is applied to this view. """ return deepcopy(self._subselection) # ------------------------------------------------------------ @property def _target_names(self): return self._modify_colnames(self._base._target_names, target) # ------------------------------------------------------------ @property def _text_names(self): return self._modify_colnames(self._base._text_names, text) # ------------------------------------------------------------ @property def _time_stamp_names(self): return self._modify_colnames(self._base._time_stamp_names, time_stamp) # ------------------------------------------------------------ @property def shape(self): """ A tuple containing the number of rows and columns of the View. """ self.refresh() return (self.nrows(), self.ncols()) # ------------------------------------------------------------
[docs] def to_arrow(self): """Creates a :py:class:`pyarrow.Table` from the view. Loads the underlying data from the getML engine and constructs a :class:`pyarrow.Table`. Returns: :class:`pyarrow.Table`: Pyarrow equivalent of the current instance including its underlying data. """ return _to_arrow(self)
# ------------------------------------------------------------
[docs] def to_json(self): """Creates a JSON string from the current instance. Loads the underlying data from the getML engine and constructs a JSON string. """ return self.to_pandas().to_json()
# ------------------------------------------------------------
[docs] def to_csv(self, fname, quotechar='"', sep=",", batch_size=0): """ Writes the underlying data into a newly created CSV file. Args: fname (str): The name of the CSV file. The ending ".csv" and an optional batch number will be added automatically. quotechar (str, optional): The character used to wrap strings. sep (str, optional): The character used for separating fields. batch_size(int, optional): Maximum number of lines per file. Set to 0 to read the entire data frame into a single file. """ # ------------------------------------------------------------ self.refresh() # ------------------------------------------------------------ if not isinstance(fname, str): raise TypeError("'fname' must be of type str") if not isinstance(quotechar, str): raise TypeError("'quotechar' 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") # ------------------------------------------------------------ fname_ = os.path.abspath(fname) # ------------------------------------------------------------ cmd = dict() cmd["type_"] = "View.to_csv" cmd["name_"] = self.name cmd["view_"] = self._getml_deserialize() cmd["fname_"] = fname_ cmd["quotechar_"] = quotechar cmd["sep_"] = sep cmd["batch_size_"] = batch_size comm.send(cmd)
# ------------------------------------------------------------
[docs] def to_db(self, table_name, conn=None): """Writes the underlying data into a newly created table in the database. Args: table_name (str): Name of the table to be created. If a table of that name already exists, it will be replaced. conn (:class:`~getml.database.Connection`, optional): 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() 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)
# ------------------------------------------------------------
[docs] def to_pandas(self): """Creates a :py:class:`pandas.DataFrame` from the view. Loads the underlying data from the getML engine and constructs a :class:`pandas.DataFrame`. Returns: :class:`pandas.DataFrame`: Pandas equivalent of the current instance including its underlying data. """ return _to_arrow(self).to_pandas()
# ------------------------------------------------------------
[docs] def to_placeholder(self, name=None): """Generates a :class:`~getml.data.Placeholder` from the current :class:`~getml.data.View`. Args: name (str, optional): 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: :class:`~getml.data.Placeholder`: A placeholder with the same name as this data frame. """ self.refresh() return Placeholder(name=name or self.name, roles=self.roles)
# ------------------------------------------------------------
[docs] def to_parquet(self, fname, compression="snappy"): """ Writes the underlying data into a newly created parquet file. Args: fname (str): The name of the parquet file. The ending ".parquet" will be added automatically. compression (str): The compression format to use. Supported values are "brotli", "gzip", "lz4", "snappy", "zstd" """ _to_parquet(self, fname, compression)
# ----------------------------------------------------------------
[docs] def to_pyspark(self, spark, name=None): """Creates a :py:class:`pyspark.sql.DataFrame` from the current instance. Loads the underlying data from the getML engine and constructs a :class:`pyspark.sql.DataFrame`. Args: spark (:py:class:`pyspark.sql.SparkSession`): The pyspark session in which you want to create the data frame. name (str or None): The name of the temporary view to be created on top of the :py:class:`pyspark.sql.DataFrame`, with which it can be referred to in Spark SQL (refer to :py:meth:`pyspark.sql.DataFrame.createOrReplaceTempView`). If none is passed, then the name of this :class:`getml.DataFrame` will be used. Returns: :py:class:`pyspark.sql.DataFrame`: Pyspark equivalent of the current instance including its underlying data. """ return _to_pyspark(self, name, spark)
# ------------------------------------------------------------ def to_s3(self, bucket, key, region, sep=",", batch_size=50000): """ Writes the underlying data into a newly created CSV file located in an S3 bucket. NOTE THAT S3 IS NOT SUPPORTED ON WINDOWS. Args: bucket (str): The bucket from which to read the files. key (str): 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 (str): The region in which the bucket is located. sep (str, optional): The character used for separating fields. batch_size(int, optional): Maximum number of lines per file. Set to 0 to read the entire data frame into a single file. Example: >>> 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() 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) # ------------------------------------------------------------
[docs] def to_s3(self, bucket, key, region, sep=",", batch_size=50000): """ Writes the underlying data into a newly created CSV file located in an S3 bucket. NOTE THAT S3 IS NOT SUPPORTED ON WINDOWS. Args: bucket (str): The bucket from which to read the files. key (str): 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 (str): The region in which the bucket is located. sep (str, optional): The character used for separating fields. batch_size(int, optional): Maximum number of lines per file. Set to 0 to read the entire data frame into a single file. Example: >>> 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() 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)
# ------------------------------------------------------------ @property def _unused_float_names(self): return self._modify_colnames(self._base._unused_float_names, unused_float) # ------------------------------------------------------------ @property def _unused_names(self): return self._unused_float_names + self._unused_string_names # ------------------------------------------------------------ @property def _unused_string_names(self): return self._modify_colnames(self._base._unused_string_names, unused_string) # ------------------------------------------------------------
[docs] def where(self, index): """Extract a subset of rows. Creates a new :class:`~getml.data.View` as a subselection of the current instance. Args: index (:class:`~getml.data.columns.BooleanColumnView` or :class:`~getml.data.columns.FloatColumnView` or :class:`~getml.data.columns.FloatColumn`): Boolean column indicating the rows you want to select. Example: Generate example data: .. code-block:: 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 .. code-block:: pycon | 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": .. code-block:: python cherries = fruits.where( fruits["fruit"] == "cherry") cherries .. code-block:: pycon | join_key | fruit | price | | join key | categorical | numerical | -------------------------------------- | 2 | cherry | 1.2 | | 2 | cherry | 1.4 | """ if isinstance(index, numbers.Integral): index = index if index > 0 else len(self) + index selector = arange(index, index + 1) return View(base=self, subselection=selector) if isinstance(index, slice): start, stop, step = _make_default_slice(index, len(self)) selector = arange(start, stop, step) return View(base=self, subselection=selector) if isinstance(index, (BooleanColumnView, FloatColumn, FloatColumnView)): return View(base=self, subselection=index) raise TypeError("Unsupported type for a subselection: " + type(index).__name__)
# ------------------------------------------------------------
[docs] def with_column( self, col, name, role=None, unit="", subroles=None, time_formats=None ): """Returns a new :class:`~getml.data.View` that contains an additional column. Args: col (:mod:`~getml.column`): The column to be added. name (str): Name of the new column. role (str, optional): Role of the new column. Must be from :mod:`getml.data.roles`. subroles (str, List[str] or None, optional): Subroles of the new column. Must be from :mod:`getml.data.subroles`. unit (str, optional): Unit of the column. time_formats (str, optional): Formats to be used to parse the time stamps. This is only necessary, if an implicit conversion from a :class:`~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 """ 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, }, )
# ------------------------------------------------------------
[docs] def with_name(self, name): """Returns a new :class:`~getml.data.View` with a new name. Args: name (str): The name of the new view. """ return View(base=self, name=name)
# ------------------------------------------------------------
[docs] def with_role(self, names, role, time_formats=None): """Returns a new :class:`~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 :code:`time_formats` argument is used to interpret :ref:`time format string <annotating_roles_time_stamp>`. For more information on roles, please refer to the :ref:`user guide <annotating>`. Args: names (str or List[str]): The name or names of the column. role (str): The role to be assigned. time_formats (str or List[str], optional): 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. """ return _with_role(self, names, role, time_formats)
# ------------------------------------------------------------
[docs] def with_subroles(self, names, subroles, append=True): """Returns a new view with one or several new subroles on one or more columns. Args: names (str or List[str]): The name or names of the column. subroles (str or List[str]): The subroles to be assigned. append (bool, optional): Whether you want to append the new subroles to the existing subroles. """ return _with_subroles(self, names, subroles, append)
# ------------------------------------------------------------
[docs] def with_unit(self, names, unit, comparison_only=False): """Returns a view that contains a new unit on one or more columns. Args: names (str or List[str]): The name or names of the column. unit (str): The unit to be assigned. comparison_only (bool): 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. """ return _with_unit(self, names, unit, comparison_only)
# ------------------------------------------------------------