teradataml.geospatial.geodataframecolumn.GeoDataFrameColumn.relates = relates(self, geom_column, amatrix)

DESCRIPTION:
    Tests if a Geometry value is spatially related to another Geometry
    value.
    Note:
        *  Using a geospatial index can greatly improve the performance of
          queries that use this method.
 
PARAMETERS:
    geom_column:
        Required Argument.
        Specifies the other Geometry value.
        Types: str, ColumnExpression, GeometryType
 
    amatrix:
        Required Argument.
        Specifies a value where each character corresponds to a cell in the
        DE-9IM pattern matrix.
        Types: str
        Notes:
            The mapping for amatrix, as defined by SQL/MM Spatial, is as follows:
            +==========+=====================================================+
            | Position | DE-9IM Cell                                         |
            +==========+=====================================================+
            | 1        | (Interior(SELF) ∩ Interior(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 2        | (Interior(SELF) ∩ Boundary(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 3        | (Interior(SELF) ∩ Exterior(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 4        | (Boundary(SELF) ∩ Interior(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 5        | (Boundary(SELF) ∩ Boundary(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 6        | (Boundary(SELF) ∩ Exterior(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 7        | (Exterior(SELF) ∩ Interior(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 8        | (Exterior(SELF) ∩ Boundary(ageometry)).dimension    |
            +----------+-----------------------------------------------------+
            | 9        | (Exterior(SELF) ∩ Exterior(ageometry)).dimension    |
            +==========+=====================================================+
 
            Valid values for each character are: 'T', 'F', '0', '1', '2', and '*'.
            The value specifies the set of acceptable values for an intersection
            at that given cell. The meaning is as follows:
            +============+==========================+
            | Cell Value | Intersection Set Results |
            +============+==========================+
            | 'T'        | { 0, 1, 2 }              |
            +------------+--------------------------+
            | 'F'        | { -1 }                   |
            +------------+--------------------------+
            | '0'        | { 0 }                    |
            +------------+--------------------------+
            | '1'        | { 1 }                    |
            +------------+--------------------------+
            | '2'        | { 2 }                    |
            +------------+--------------------------+
            | '*'        | { -1, 0, 1, 2 }          |
            +============+==========================+
 
SUPPORTED GEOMETRY TYPES:
    All Geometry types except geometry collections.
    Note:
        This method can be called on 3D geometries (those that include Z
        coordinates). However, the Z coordinate is ignored in method
        calculations.
 
RAISES:
    TypeError, ValueError, TeradataMlException
 
RETURNS:
    GeoDataFrameColumn
    Resultant column contains:
        * 1, if the spatial relationship between the geometries corresponds
          to one of the acceptable values represented by "amatrix"
        * 0, if the spatial relationship between the geometries does not
          correspond to one of the acceptable values represented by "amatrix"
 
EXAMPLES:
    from teradataml import GeoDataFrame, load_example_data
    from teradataml import Point, LineString, Polygon, GeometryCollection
    # Load example data.
    load_example_data("geodataframe", "sample_shapes")
    # Create a GeoDataFrame.
    geodf = GeoDataFrame("sample_shapes")
    print(geodf)
 
    # Example 1: Check if geometry values in column 'points' are spatially related to
    #            geometry values in column 'linestrings'.
    # Let's select only few columns from GeoDataFrame.
    point_lines = geodf.select(["skey", "points", "linestrings"])
    relates = point_lines.points.relates(geom_column=point_lines.linestrings, amatrix="0********")
    point_lines.assign(res = relates)
 
    # Example 2: Filter rows if geometry values in column 'points' are spatially related to
    #            geometry values in column 'linestrings'.
    relates = point_lines.points.relates(geom_column=point_lines.linestrings, amatrix="0********")
    point_lines[relates == 1]