Skip to content

Variables

s3lst_ds.utilities.var_utils

Classes:

Name Description
DataVars

Class with aliases and units for predictors and target and their kinds.

DataVars

Class with aliases and units for predictors and target and their kinds.

Attributes:

Name Type Description
alias_fancy dict[str, str]

Class attribute: mapper between variable aliases and their fancy counterparts.
units_fancy dict[str, str]

Class attribute: mapper between variable aliases and their fancy units.
X_xt list[str]

Base attribute: aliases of the spatio-temporal predictors. Default corresponds to a list containing: - "NDVI" - "FVC" - "NDWI"
X_x list[str]

Base attribute: aliases of the pure spatial predictors. Default corresponds to a list containing: - "TCD" - "DEM" - "IMD" - "TOPEX" - "COASTDIST" - "LCZ" - "UD"
X_t list[str]

Base attribute: aliases of the pure temporal predictors. Default corresponds to a list containing: - "timestamp" - "season"
X_cat list[str]

Base attribute: aliases of the categorical predictors. Default corresponds to a list containing: - "LCZ", - "timestamp", - "season".
y str

Base attribute: alias of the target variable. Default corresponds to "LST".
y_val str

Base attribute: alias of the validating target variable. Default corresponds to "LST_landsat".
X_num list[str]

Derived attribute: aliases of the numerical predictors.
X list[str]

Derived attribute: aliases of all predictors (numerical and categorical).
vars_xt list[str]

Derived attribute: aliases of the spatio-temporal variables (spatio-temporal predictors and target including the validating target).
vars_x list[str]

Derived attribute: aliases of the pure spatial variables (spatial predictors).
vars_t list[str]

Derived attribute: aliases of the pure temporal variables (temporal predictors).
vars_num list[str]

Derived attribute: aliases of the numerical variables (numerical predictors and target, including the validating target).
vars_cat list[str]

Derived attribute: aliases of the categorical variables (categorical predictors).
vars list[str]

Derived attribute: aliases of all variables (predictors and target).

Methods:

Name Description
__init__
add_X

Add alias X of a predictor of spatio-temporal kind kind_xt and categorical
remove_X

Remove predictor aliases X and update the derived variable accordingly.
set_y

Set y as target alias.
set_y_val

Set y_val as validating target alias.
subset_X

Subset predictor aliases to X and update the derived variable accordingly.
Source code in src/s3lst_ds/utilities/var_utils.py 
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
class DataVars:
    """
    Class with aliases and units for predictors and target and their kinds.

    Attributes
    ----------
    alias_fancy : dict[str, str]
        Class attribute: mapper between variable aliases and their fancy counterparts.

    units_fancy : dict[str, str]
        Class attribute: mapper between variable aliases and their fancy units.

    X_xt : list[str]
        Base attribute: aliases of the spatio-temporal predictors. Default corresponds
        to a list containing:
            - `"NDVI"`
            - `"FVC"`
            - `"NDWI"`

    X_x : list[str]
        Base attribute: aliases of the pure spatial predictors. Default corresponds to a
        list containing:
            - `"TCD"`
            - `"DEM"`
            - `"IMD"`
            - `"TOPEX"`
            - `"COASTDIST"`
            - `"LCZ"`
            - `"UD"`

    X_t : list[str]
        Base attribute: aliases of the pure temporal predictors. Default corresponds to
        a list containing:
            - `"timestamp"`
            - `"season"`

    X_cat : list[str]
        Base attribute: aliases of the categorical predictors. Default corresponds to a
        list containing:
            - `"LCZ"`,
            - `"timestamp"`,
            - `"season"`.

    y : str
        Base attribute: alias of the target variable. Default corresponds to `"LST"`.

    y_val : str
        Base attribute: alias of the validating target variable. Default corresponds to
        `"LST_landsat"`.

    X_num : list[str]
        Derived attribute: aliases of the numerical predictors.

    X : list[str]
        Derived attribute: aliases of all predictors (numerical and categorical).

    vars_xt : list[str]
        Derived attribute: aliases of the spatio-temporal variables (spatio-temporal
        predictors and target including the validating target).

    vars_x : list[str]
        Derived attribute: aliases of the pure spatial variables (spatial predictors).

    vars_t : list[str]
        Derived attribute: aliases of the pure temporal variables (temporal predictors).

    vars_num : list[str]
        Derived attribute: aliases of the numerical variables (numerical predictors and
        target, including the validating target).

    vars_cat : list[str]
        Derived attribute: aliases of the categorical variables (categorical
        predictors).

    vars : list[str]
        Derived attribute: aliases of all variables (predictors and target).
    """

    alias_fancy: ClassVar[dict[str, str]] = {
        "NDVI": r"$\mathrm{NDVI}$",
        "FVC": r"$\mathrm{FVC}$",
        "NDWI": r"$\mathrm{NDWI}$",
        "TCD": r"$\mathrm{TCD}$",
        "DEM": r"$\mathrm{DEM}$",
        "IMD": r"$\mathrm{IMD}$",
        "TOPEX": r"$\mathrm{TOPEX}$",
        "COASTDIST": r"$\mathrm{DCOAST}$",
        "LCZ": r"$\mathrm{LCZ}$",
        "UD": r"$\mathrm{UD}$",
        "timestamp": r"$\mathrm{Timestamp}$",
        "season": r"$\mathrm{Season}$",
        "LST": r"$\mathrm{LST}$",
        "LST_landsat": r"$\mathrm{LST}$",
    }

    units_fancy: ClassVar[dict[str, str]] = {
        "NDVI": r" $[-]$",
        "FVC": r" $[-]$",
        "NDWI": r" $[-]$",
        "LST": r" $[\mathrm{K}]$",
        "LST_landsat": r" $[\mathrm{K}]$",
    }

    def __init__(
        self,
        X_xt: list[str] | None = None,
        X_x: list[str] | None = None,
        X_t: list[str] | None = None,
        X_cat: list[str] | None = None,
        y: str | None = None,
        y_val: str | None = None,
    ) -> None:

        self.X_xt = (
            X_xt
            if X_xt is not None
            else [
                "NDVI",
                "FVC",
                "NDWI",
            ]
        )
        self.X_x = (
            X_x
            if X_x is not None
            else [
                "TCD",
                "DEM",
                "IMD",
                "TOPEX",
                "COASTDIST",
                "LCZ",
                "UD",
            ]
        )
        self.X_t = (
            X_t
            if X_t is not None
            else [
                "timestamp",
                "season",
            ]
        )
        self.X_cat = (
            X_cat
            if X_cat is not None
            else [
                "LCZ",
                "timestamp",
                "season",
            ]
        )
        self.y = y if y is not None else "LST"
        self.y_val = y_val if y_val is not None else "LST_landsat"

        # Define derived attributes
        self._update()

    def _update(self) -> None:
        """
        Update derived attributes. The derived attributes are:
        - `X_num` (`list[str]`): aliases of the numerical predictors.
        - `X` (`list[str]`): aliases of all predictors (numerical and categorical).
        - `vars_xt` (`list[str]`): aliases of the spatio-temporal variables
        (spatio-temporal predictors and target).
        - `vars_x` (`list[str]`): aliases of the pure spatial variables (spatial
        predictors).
        - `vars_t` (`list[str]`): aliases of the pure temporal variables (temporal
        predictors).
        - `vars_num` (`list[str]`): aliases of the numerical variables (numerical
        predictors and target).
        - `vars_cat` (`list[str]`): aliases of the categorical variables
        (categorical predictors).
        - `vars` (`list[str]`): aliases of all variables (predictors and target).
        """
        self.X_num = difference(self.X_xt + self.X_x + self.X_t, self.X_cat)

        self.X = self.X_num + self.X_cat  # type: ignore
        self.vars_xt = self.X_xt + [self.y, self.y_val]
        self.vars_x = self.X_x
        self.vars_t = self.X_t
        self.vars_num = self.X_num + [self.y, self.y_val]  # type: ignore
        self.vars_cat = self.X_cat
        self.vars = self.vars_num + self.vars_cat

    def set_y(self, y: str) -> "DataVars":
        """
        Set `y` as target alias.

        Parameters
        ----------
        y : str
            Target alias to set.

        Returns
        -------

        data_vars : DataVars
            A new `DataVars` instance with the issued target alias `y` and derived
            parameters updated.
        """

        # Create a copy of the current instance with the issued `y`
        data_vars = DataVars(
            X_xt=self.X_xt,
            X_x=self.X_x,
            X_t=self.X_t,
            X_cat=self.X_cat,
            y=y,
            y_val=self.y_val,
        )
        return data_vars

    def set_y_val(self, y_val: str) -> "DataVars":
        """
        Set `y_val` as validating target alias.

        Parameters
        ----------
        y_val : str
            Validating target alias to set.

        Returns
        -------

        data_vars : DataVars
            A new `DataVars` instance with the issued validating target alias `y_val`
            and derived parameters updated.
        """

        # Create a copy of the current instance with the issued `y_val`
        data_vars = DataVars(
            X_xt=self.X_xt,
            X_x=self.X_x,
            X_t=self.X_t,
            X_cat=self.X_cat,
            y=self.y,
            y_val=y_val,
        )
        return data_vars

    def subset_X(self, X: list[str]) -> "DataVars":
        """
        Subset predictor aliases to `X` and update the derived variable accordingly.

        Parameters
        ----------
        X : list[str]
            Predictor aliases to keep.

        Returns
        -------
        data_vars : DataVars
            A new `DataVars` instance with the issued predictor aliases `X` and derived
            parameters updated.
        """

        # Create a copy of the current instance with the predictor aliases subsetted to
        # the ones of interest
        data_vars = DataVars(
            X_xt=intersection(X, self.X_xt),  # type: ignore
            X_x=intersection(X, self.X_x),  # type: ignore
            X_t=intersection(X, self.X_t),  # type: ignore
            X_cat=intersection(X, self.X_cat),  # type: ignore
            y=self.y,
            y_val=self.y_val,
        )
        return data_vars

    def remove_X(self, X: str | list[str]) -> "DataVars":
        """
        Remove predictor aliases `X` and update the derived variable accordingly.

        Parameters
        ----------
        X : str or list[str]
            Predictor aliases to remove.

        Returns
        -------
        data_vars : DataVars
            A new `DataVars` instance with the issued predictor aliases `X` removed and
            derived parameters updated.
        """

        X = [X] if isinstance(X, str) else X

        # Create a copy of the current instance with the issued predictor aliases
        # removed
        data_vars = DataVars(
            X_xt=difference(self.X_xt, X),  # type: ignore
            X_x=difference(self.X_x, X),  # type: ignore
            X_t=difference(self.X_t, X),  # type: ignore
            X_cat=difference(self.X_cat, X),  # type: ignore
            y=self.y,
            y_val=self.y_val,
        )
        return data_vars

    def add_X(self, X: str, kind_xt: Literal["xt", "x", "t"], cat: bool) -> "DataVars":
        """
        Add alias `X` of a predictor of spatio-temporal kind `kind_xt` and categorical
        predictor indication `cat`, and update the derived variable accordingly.

        Parameters
        ----------
        X : str
            Predictor alias to add.

        kind_xt : {"xt", "x", "t"}
            Spatio-temporal kind of the predictor to add. It can be:
            - `"xt"`: spatio-temporal predictor.
            - `"x"`: pure spatial predictor.
            - `"t"`: pure temporal predictor.

        cat : bool
            Whether the predictor to add is categorical or not.

        Returns
        -------
        data_vars : DataVars
            A new `DataVars` instance with the issued predictor alias `X` added and
            derived parameters updated.
        """

        # Create a copy of the current instance with the issued predictor aliases added
        data_vars = DataVars(
            X_xt=union(self.X_xt, X) if kind_xt == "xt" else self.X_xt,  # type: ignore
            X_x=union(self.X_x, X) if kind_xt == "x" else self.X_x,  # type: ignore
            X_t=union(self.X_t, X) if kind_xt == "t" else self.X_t,  # type: ignore
            X_cat=union(self.X_cat, X) if cat else self.X_cat,  # type: ignore
            y=self.y,
            y_val=self.y_val,
        )
        return data_vars

X_cat instance-attribute 

X_cat = X_cat if X_cat is not None else ['LCZ', 'timestamp', 'season']

X_t instance-attribute 

X_t = X_t if X_t is not None else ['timestamp', 'season']

X_x instance-attribute 

X_x = (
    X_x if X_x is not None else ["TCD", "DEM", "IMD", "TOPEX", "COASTDIST", "LCZ", "UD"]
)

X_xt instance-attribute 

X_xt = X_xt if X_xt is not None else ['NDVI', 'FVC', 'NDWI']

alias_fancy class-attribute 

alias_fancy: dict[str, str] = {
    "NDVI": "$\\mathrm{NDVI}$",
    "FVC": "$\\mathrm{FVC}$",
    "NDWI": "$\\mathrm{NDWI}$",
    "TCD": "$\\mathrm{TCD}$",
    "DEM": "$\\mathrm{DEM}$",
    "IMD": "$\\mathrm{IMD}$",
    "TOPEX": "$\\mathrm{TOPEX}$",
    "COASTDIST": "$\\mathrm{DCOAST}$",
    "LCZ": "$\\mathrm{LCZ}$",
    "UD": "$\\mathrm{UD}$",
    "timestamp": "$\\mathrm{Timestamp}$",
    "season": "$\\mathrm{Season}$",
    "LST": "$\\mathrm{LST}$",
    "LST_landsat": "$\\mathrm{LST}$",
}

units_fancy class-attribute 

units_fancy: dict[str, str] = {
    "NDVI": " $[-]$",
    "FVC": " $[-]$",
    "NDWI": " $[-]$",
    "LST": " $[\\mathrm{K}]$",
    "LST_landsat": " $[\\mathrm{K}]$",
}

y instance-attribute 

y = y if y is not None else 'LST'

y_val instance-attribute 

y_val = y_val if y_val is not None else 'LST_landsat'

__init__ 

__init__(
    X_xt: list[str] | None = None,
    X_x: list[str] | None = None,
    X_t: list[str] | None = None,
    X_cat: list[str] | None = None,
    y: str | None = None,
    y_val: str | None = None,
) -> None
Source code in src/s3lst_ds/utilities/var_utils.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
def __init__(
    self,
    X_xt: list[str] | None = None,
    X_x: list[str] | None = None,
    X_t: list[str] | None = None,
    X_cat: list[str] | None = None,
    y: str | None = None,
    y_val: str | None = None,
) -> None:

    self.X_xt = (
        X_xt
        if X_xt is not None
        else [
            "NDVI",
            "FVC",
            "NDWI",
        ]
    )
    self.X_x = (
        X_x
        if X_x is not None
        else [
            "TCD",
            "DEM",
            "IMD",
            "TOPEX",
            "COASTDIST",
            "LCZ",
            "UD",
        ]
    )
    self.X_t = (
        X_t
        if X_t is not None
        else [
            "timestamp",
            "season",
        ]
    )
    self.X_cat = (
        X_cat
        if X_cat is not None
        else [
            "LCZ",
            "timestamp",
            "season",
        ]
    )
    self.y = y if y is not None else "LST"
    self.y_val = y_val if y_val is not None else "LST_landsat"

    # Define derived attributes
    self._update()

add_X 

add_X(X: str, kind_xt: Literal['xt', 'x', 't'], cat: bool) -> DataVars

Add alias X of a predictor of spatio-temporal kind kind_xt and categorical predictor indication cat, and update the derived variable accordingly.

Parameters:

Name Type Description Default
X str

Predictor alias to add.

 required
kind_xt (xt, x, t)

Spatio-temporal kind of the predictor to add. It can be: - "xt": spatio-temporal predictor. - "x": pure spatial predictor. - "t": pure temporal predictor.

 "xt"
cat bool

Whether the predictor to add is categorical or not.

 required

Returns:

Name Type Description
data_vars DataVars

A new DataVars instance with the issued predictor alias X added and derived parameters updated.
Source code in src/s3lst_ds/utilities/var_utils.py 
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
def add_X(self, X: str, kind_xt: Literal["xt", "x", "t"], cat: bool) -> "DataVars":
    """
    Add alias `X` of a predictor of spatio-temporal kind `kind_xt` and categorical
    predictor indication `cat`, and update the derived variable accordingly.

    Parameters
    ----------
    X : str
        Predictor alias to add.

    kind_xt : {"xt", "x", "t"}
        Spatio-temporal kind of the predictor to add. It can be:
        - `"xt"`: spatio-temporal predictor.
        - `"x"`: pure spatial predictor.
        - `"t"`: pure temporal predictor.

    cat : bool
        Whether the predictor to add is categorical or not.

    Returns
    -------
    data_vars : DataVars
        A new `DataVars` instance with the issued predictor alias `X` added and
        derived parameters updated.
    """

    # Create a copy of the current instance with the issued predictor aliases added
    data_vars = DataVars(
        X_xt=union(self.X_xt, X) if kind_xt == "xt" else self.X_xt,  # type: ignore
        X_x=union(self.X_x, X) if kind_xt == "x" else self.X_x,  # type: ignore
        X_t=union(self.X_t, X) if kind_xt == "t" else self.X_t,  # type: ignore
        X_cat=union(self.X_cat, X) if cat else self.X_cat,  # type: ignore
        y=self.y,
        y_val=self.y_val,
    )
    return data_vars

remove_X 

remove_X(X: str | list[str]) -> DataVars

Remove predictor aliases X and update the derived variable accordingly.

Parameters:

Name Type Description Default
X str or list[str]

Predictor aliases to remove.

 required

Returns:

Name Type Description
data_vars DataVars

A new DataVars instance with the issued predictor aliases X removed and derived parameters updated.
Source code in src/s3lst_ds/utilities/var_utils.py 
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
def remove_X(self, X: str | list[str]) -> "DataVars":
    """
    Remove predictor aliases `X` and update the derived variable accordingly.

    Parameters
    ----------
    X : str or list[str]
        Predictor aliases to remove.

    Returns
    -------
    data_vars : DataVars
        A new `DataVars` instance with the issued predictor aliases `X` removed and
        derived parameters updated.
    """

    X = [X] if isinstance(X, str) else X

    # Create a copy of the current instance with the issued predictor aliases
    # removed
    data_vars = DataVars(
        X_xt=difference(self.X_xt, X),  # type: ignore
        X_x=difference(self.X_x, X),  # type: ignore
        X_t=difference(self.X_t, X),  # type: ignore
        X_cat=difference(self.X_cat, X),  # type: ignore
        y=self.y,
        y_val=self.y_val,
    )
    return data_vars

set_y 

set_y(y: str) -> DataVars

Set y as target alias.

Parameters:

Name Type Description Default
y str

Target alias to set.

 required

Returns:

Name Type Description
data_vars DataVars

A new DataVars instance with the issued target alias y and derived parameters updated.
Source code in src/s3lst_ds/utilities/var_utils.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
def set_y(self, y: str) -> "DataVars":
    """
    Set `y` as target alias.

    Parameters
    ----------
    y : str
        Target alias to set.

    Returns
    -------

    data_vars : DataVars
        A new `DataVars` instance with the issued target alias `y` and derived
        parameters updated.
    """

    # Create a copy of the current instance with the issued `y`
    data_vars = DataVars(
        X_xt=self.X_xt,
        X_x=self.X_x,
        X_t=self.X_t,
        X_cat=self.X_cat,
        y=y,
        y_val=self.y_val,
    )
    return data_vars

set_y_val 

set_y_val(y_val: str) -> DataVars

Set y_val as validating target alias.

Parameters:

Name Type Description Default
y_val str

Validating target alias to set.

 required

Returns:

Name Type Description
data_vars DataVars

A new DataVars instance with the issued validating target alias y_val and derived parameters updated.
Source code in src/s3lst_ds/utilities/var_utils.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
def set_y_val(self, y_val: str) -> "DataVars":
    """
    Set `y_val` as validating target alias.

    Parameters
    ----------
    y_val : str
        Validating target alias to set.

    Returns
    -------

    data_vars : DataVars
        A new `DataVars` instance with the issued validating target alias `y_val`
        and derived parameters updated.
    """

    # Create a copy of the current instance with the issued `y_val`
    data_vars = DataVars(
        X_xt=self.X_xt,
        X_x=self.X_x,
        X_t=self.X_t,
        X_cat=self.X_cat,
        y=self.y,
        y_val=y_val,
    )
    return data_vars

subset_X 

subset_X(X: list[str]) -> DataVars

Subset predictor aliases to X and update the derived variable accordingly.

Parameters:

Name Type Description Default
X list[str]

Predictor aliases to keep.

 required

Returns:

Name Type Description
data_vars DataVars

A new DataVars instance with the issued predictor aliases X and derived parameters updated.
Source code in src/s3lst_ds/utilities/var_utils.py 
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
def subset_X(self, X: list[str]) -> "DataVars":
    """
    Subset predictor aliases to `X` and update the derived variable accordingly.

    Parameters
    ----------
    X : list[str]
        Predictor aliases to keep.

    Returns
    -------
    data_vars : DataVars
        A new `DataVars` instance with the issued predictor aliases `X` and derived
        parameters updated.
    """

    # Create a copy of the current instance with the predictor aliases subsetted to
    # the ones of interest
    data_vars = DataVars(
        X_xt=intersection(X, self.X_xt),  # type: ignore
        X_x=intersection(X, self.X_x),  # type: ignore
        X_t=intersection(X, self.X_t),  # type: ignore
        X_cat=intersection(X, self.X_cat),  # type: ignore
        y=self.y,
        y_val=self.y_val,
    )
    return data_vars