Local Climate Zones

s3lst_ds.utilities.lcz

Local Climate Zone (LCZ) utilities.

Classes:

Name	Description
LCZ	Local Climate Zone (LCZ) class (a subclass of LCZBase) for handling LCZ codes,

__all__ module-attribute

__all__ = ['LCZ']

LCZ

Bases: LCZBase

Local Climate Zone (LCZ) class (a subclass of LCZBase) for handling LCZ codes, labels, descriptions, colors and indexes and their inter-conversion.

Methods:

Name	Description
__init_subclass__
convert	Convert values of a source variable into a target one. The supported
get_mapper	Get DataFrame mapper between LCZ codes, labels, descriptions, colors and
get_unique_mapper_values	Get unique values of LCZ's DataFrame mapper variables.

Attributes:

Name	Type	Description
path_mapper
vars_cat	tuple[str, ...]

Source code in src/s3lst_ds/utilities/lcz/_base.py

class LCZ(LCZBase):
    """
    Local Climate Zone (LCZ) class (a subclass of `LCZBase`) for handling LCZ codes,
    labels, descriptions, colors and indexes and their inter-conversion.
    """

path_mapper class-attribute instance-attribute

path_mapper = Path(__file__).resolve().parent / '_mapper.csv'

vars_cat class-attribute

vars_cat: tuple[str, ...] = ('code', 'label', 'description', 'color', 'index')

__init_subclass__

__init_subclass__()

Source code in src/s3lst_ds/utilities/lcz/_base.py

def __init_subclass__(cls):
    cls.mapper = cls.get_mapper()
    cls.values = cls.get_unique_mapper_values()

convert classmethod

convert(values: Series, source: str, target: str) -> Series

Convert values of a source variable into a target one. The supported source and target variables correspond to the mapper variables:

- `"code"`;
- `"label"`;
- `"description"`;
- `"color"`;
- `"index"`.

Parameters:

Name	Type	Description	Default
cls	type	A LCZ class.	required
values	Series	The values to convert.	required
source	str	The variable associated with the issued values.	required
target	str	The variable to convert the values into.	required

Returns:

Name	Type	Description
converted_values	Series	The respective converted values.

Source code in src/s3lst_ds/utilities/lcz/_base.py

@classmethod
def convert(
    cls,
    values: pd.Series,
    source: str,
    target: str,
) -> pd.Series:
    """
    Convert `values` of a `source` variable into a `target` one. The supported
    `source` and `target` variables correspond to the `mapper` variables:

        - `"code"`;
        - `"label"`;
        - `"description"`;
        - `"color"`;
        - `"index"`.

    Parameters
    ----------
    cls : type
        A `LCZ` class.
    values : pd.Series
        The values to convert.
    source : str
        The variable associated with the issued `values`.
    target : str
        The variable to convert the `values` into.

    Returns
    -------
    converted_values : pd.Series
        The respective converted values.
    """

    # If the source variable is an LCZ code, convert the values to string if they
    # are not already (as the mapper assumes that they have this type)
    if source in [
        "code",
    ] and not pd.api.types.is_object_dtype(values):
        # NOTE: the values are converted to integers before being converted to
        # strings to avoid decimal points appearing in the strings in the case of
        # the data being originally floats. Also, a value-by-value conversion is
        # required for the case of the values corresponding to floats and containing
        # nan.
        values = values.apply(
            lambda value: str(int(value)) if pd.notna(value) else None
        )

    # Get target values from source ones
    converted_values = values.map(cls.mapper.set_index(source)[target])

    # Convert target values to a categorical Series if the target variable is a
    # categorical one
    if target in cls.vars_cat:
        converted_values = pd.Series(
            data=pd.Categorical(
                values=converted_values,
                categories=cls.values[target],
            ),
            index=converted_values.index,
        )

    return converted_values

get_mapper classmethod

get_mapper() -> DataFrame

Get DataFrame mapper between LCZ codes, labels, descriptions, colors and indexes.

Parameters:

Name	Type	Description	Default
cls	type	An LCZ class.	required

Returns:

Name	Type	Description
mapper	DataFrame	The mapper.

Source code in src/s3lst_ds/utilities/lcz/_base.py

@classmethod
def get_mapper(cls) -> pd.DataFrame:
    """
    Get DataFrame mapper between LCZ codes, labels, descriptions, colors and
    indexes.

    Parameters
    ----------
    cls : type
        An `LCZ` class.

    Returns
    -------
    mapper : pd.DataFrame
        The mapper.
    """

    # Get mapper associated with LCZ attributes
    mapper = pd.read_csv(
        cls.path_mapper,
        dtype={
            "code": str,
            "label": str,
            "description": str,
            "color": str,
            "index": int,
        },
    )

    return mapper

get_unique_mapper_values classmethod

get_unique_mapper_values() -> dict[str, list]

Get unique values of LCZ's DataFrame mapper variables.

Parameters:

Name	Type	Description	Default
cls	type	An LCZ class.	required

Returns:

Name	Type	Description
values	dict[str, list]	A dictionary of lists of unique values of LCZ's DataFrame mapper variables, keyed by variable.

Source code in src/s3lst_ds/utilities/lcz/_base.py

@classmethod
def get_unique_mapper_values(cls) -> dict[str, list]:
    """
    Get unique values of LCZ's DataFrame `mapper` variables.

    Parameters
    ----------
    cls : type
        An `LCZ` class.

    Returns
    -------
    values : dict[str, list]
        A dictionary of lists of unique values of LCZ's DataFrame `mapper`
        variables, keyed by variable.
    """

    # Get unique values of LCZ's DataFrame mapper variables
    values = {var: cls.mapper[var].unique().tolist() for var in cls.mapper.columns}

    return values  # type: ignore