getml.data.Placeholder

def join(
    self,
    right: "Placeholder",
    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 another to placeholder to this placeholder.

    Args:
        right:
            The placeholder you would like to join.

        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* that serves as an upper limit
            on the join.
    """

    if not isinstance(right, type(self)):
        msg = (
            "'right' must be a getml.data.Placeholder. "
            + "You can create a placeholder by calling .to_placeholder() "
            + "on DataFrames or Views."
        )
        raise TypeError(msg)

    if self in right.to_list():
        raise ValueError(
            "Cicular references to other placeholders are not allowed."
        )

    sanitized_on = _handle_on(on)

    if isinstance(time_stamps, str):
        time_stamps = (time_stamps, time_stamps)

    keys_by_ph = list(zip(*sanitized_on))

    for i, ph in enumerate([self, right]):
        if ph.roles.join_key:
            if ph_keys := keys_by_ph[i]:
                _check_join_key(ph_keys, ph.roles, ph.name)

        if ph.roles.time_stamp and time_stamps:
            if time_stamps[i] not in ph.roles.time_stamp:
                raise ValueError(f"Not a time stamp: {time_stamps[i]}.")

    if lagged_targets and horizon in (0.0, None):
        raise ValueError(
            "Setting 'lagged_targets' to True requires a positive, non-zero "
            "'horizon'  to avoid data leakage."
        )

    if horizon not in (0.0, None) and time_stamps is None:
        raise ValueError(
            "Setting 'horizon' (i.e. a relative look-back window) requires "
            "setting 'time_stamps'."
        )

    if memory not in (0.0, None) and time_stamps is None:
        raise ValueError("Setting 'horizon' requires setting 'time_stamps'.")

    join = Join(
        right=right,
        on=sanitized_on,
        time_stamps=time_stamps,
        relationship=relationship,
        memory=memory,
        horizon=horizon,
        lagged_targets=lagged_targets,
        upper_time_stamp=upper_time_stamp,
    )

    if any(join == existing for existing in self.joins):
        raise ValueError(
            "A join with the following set of parameters already exists on "
            f"the placeholder {self.name!r}:"
            f"\n\n{join}\n\n"
            "Redundant joins are not allowed."
        )

    self.joins.append(join)
    right.parent = self  # type: ignore

def to_list(self):
    """
    Returns a list of this placeholder and all of its descendants.
    """
    return [self] + [ph for join in self.joins for ph in join.right.to_list()]

def to_dict(self):
    """
    Expresses this placeholder and all of its descendants as a dictionary.
    """
    phs = {}
    for ph in self.to_list():
        key = ph.name
        if ph.children:
            i = 2
            while key in phs:
                key = f"{ph.name}{i}"
                i += 1
        phs[key] = ph
    return phs