getml.data.StarSchema

def join(
    self,
    right_df: Union[DataFrame, View],
    alias: Optional[str] = None,
    on: OnType = None,
    time_stamps: TimeStampsType = None,
    relationship: str = many_to_many,
    memory: Optional[float] = None,
    horizon: Optional[float] = None,
    lagged_targets: bool = False,
    upper_time_stamp: Optional[str] = None,
):
    """
    Joins a [`DataFrame`][getml.DataFrame] or [`View`][getml.data.View]
    to the population table.

    In a [`StarSchema`][getml.data.StarSchema] or [`TimeSeries`][getml.data.TimeSeries],
    all joins take place on the population table. If you want to create more
    complex data models, use [`DataModel`][getml.data.DataModel] instead.

    ??? example
        This example will construct a data model in which the
        'population_table' depends on the 'peripheral_table' via
        the 'join_key' column. In addition, only those rows in
        'peripheral_table' for which 'time_stamp' is smaller or
        equal to the 'time_stamp' in 'population_table' are considered:

        ```python
        star_schema = getml.data.StarSchema(
            population=population_table, split=split)

        star_schema.join(
            peripheral_table,
            on="join_key",
            time_stamps="time_stamp"
        )
        ```

        If the relationship between two tables is many-to-one or one-to-one
        you should clearly say so:
        ```python
        star_schema.join(
            peripheral_table,
            on="join_key",
            time_stamps="time_stamp",
            relationship=getml.data.relationship.many_to_one,
        )
        ```
        Please also refer to [`relationship`][getml.data.relationship].

        If the join keys or time stamps are named differently in the two
        different tables, use a tuple:

        ```python
        star_schema.join(
            peripheral_table,
            on=("join_key", "other_join_key"),
            time_stamps=("time_stamp", "other_time_stamp"),
        )
        ```

        You can join over more than one join key:

        ```python
        star_schema.join(
            peripheral_table,
            on=["join_key1", "join_key2", ("join_key3", "other_join_key3")],
            time_stamps="time_stamp",
            )
        ```

        You can also limit the scope of your joins using *memory*. This
        can significantly speed up training time. For instance, if you
        only want to consider data from the last seven days, you could
        do something like this:

        ```python
        star_schema.join(
            peripheral_table,
            on="join_key",
            time_stamps="time_stamp",
            memory=getml.data.time.days(7),
        )
        ```

        In some use cases, particularly those involving time series, it
        might be a good idea to use targets from the past. You can activate
        this using *lagged_targets*. But if you do that, you must
        also define a prediction *horizon*. For instance, if you want to
        predict data for the next hour, using data from the last seven days,
        you could do this:

        ```python
        star_schema.join(
            peripheral_table,
            on="join_key",
            time_stamps="time_stamp",
            lagged_targets=True,
            horizon=getml.data.time.hours(1),
            memory=getml.data.time.days(7),
        )
        ```

        Please also refer to [`time`][getml.data.time].

        If the join involves many matches, it might be a good idea to set the
        relationship to [`propositionalization`][getml.data.relationship.propositionalization].
        This forces the pipeline to always use a propositionalization
        algorithm for this join, which can significantly speed things up.

        ```python
        star_schema.join(
            peripheral_table,
            on="join_key",
            time_stamps="time_stamp",
            relationship=getml.data.relationship.propositionalization,
        )
        ```

        Please also refer to [`relationship`][getml.data.relationship].

    Args:
        right_df:
            The data frame or view you would like to join.

        alias:
            The name as which you want *right_df* to be referred to in
            the generated SQL code.

        on:
            The join keys to use. If none is passed, then everything
            will be joined to everything else.

        time_stamps:
            The time stamps used to limit the join.

        relationship:
            The relationship between the two tables. Must be from
            [`relationship`][getml.data.relationship].

        memory:
            The difference between the time stamps until data is 'forgotten'.
            Limiting your joins using memory can significantly speed up
            training time. Also refer to [`time`][getml.data.time].

        horizon:
            The prediction horizon to apply to this join.
            Also refer to [`time`][getml.data.time].

        lagged_targets:
            Whether you want to allow lagged targets. If this is set to True,
            you must also pass a positive, non-zero *horizon*.

        upper_time_stamp:
            Name of a time stamp in *right_df* that serves as an upper limit
            on the join.
    """

    if not isinstance(right_df, (DataFrame, View)):
        raise TypeError(
            f"Expected a {DataFrame} as 'right_df', got: {type(right_df)}."
        )

    if isinstance(right_df, View):
        if alias is None:
            raise ValueError(
                "Setting an 'alias' is required if a getml.data.View is supplied "
                "as a peripheral table."
            )

    def modify_join_keys(on):
        if isinstance(on, list):
            return [modify_join_keys(jk) for jk in on]

        if isinstance(on, (str, StringColumn)):
            on = (on, on)

        if on is not None and on:
            on = tuple(
                jkey.name if isinstance(jkey, StringColumn) else jkey for jkey in on
            )

        return on

    def modify_time_stamps(time_stamps):
        if isinstance(time_stamps, (str, FloatColumn)):
            time_stamps = (time_stamps, time_stamps)

        if time_stamps is not None:
            time_stamps = tuple(
                time_stamp.name
                if isinstance(time_stamp, FloatColumn)
                else time_stamp
                for time_stamp in time_stamps
            )

        return time_stamps

    on = modify_join_keys(on)

    time_stamps = modify_time_stamps(time_stamps)

    upper_time_stamp = (
        upper_time_stamp.name
        if isinstance(upper_time_stamp, FloatColumn)
        else upper_time_stamp
    )

    right = right_df.to_placeholder(alias)

    self.data_model.population.join(
        right=right,
        on=on,
        time_stamps=time_stamps,
        relationship=relationship,
        memory=memory,
        horizon=horizon,
        lagged_targets=lagged_targets,
        upper_time_stamp=upper_time_stamp,
    )

    alias = alias or right_df.name

    self.container.add(**{alias: right_df})

def sync(self):
    """
    Synchronizes the last change with the data to avoid warnings that the data
    has been changed.

    This is only a problem when `deep_copy=False`.
    """
    self.container.sync()