Skip to content

downscale.base

Downscaler interface and the generic proportional implementation.

Region→country and country→bus are the same operation: distribute a coarse value over its finer members proportionally to proxy shares (population/GDP/SSP activity, ...). The shares are built by :mod:iampypsa.downscale.proxy.

Downscaler

Bases: ABC

Define how coarse values are distributed to finer units.

Source code in src/iampypsa/downscale/base.py 
13
14
15
16
17
18
19
class Downscaler(ABC):
    """Define how coarse values are distributed to finer units."""

    @abstractmethod
    def downscale(self, coarse: pd.DataFrame, proxy_shares: pd.DataFrame) -> pd.DataFrame:
        """Distribute coarse values to finer units using proxy shares."""
        ...

downscale(coarse, proxy_shares) abstractmethod

Distribute coarse values to finer units using proxy shares.

Source code in src/iampypsa/downscale/base.py 
16
17
18
19
@abstractmethod
def downscale(self, coarse: pd.DataFrame, proxy_shares: pd.DataFrame) -> pd.DataFrame:
    """Distribute coarse values to finer units using proxy shares."""
    ...

ProportionalDownscaler

Bases: Downscaler

Distribute coarse values to finer units in proportion to proxy shares.

Source code in src/iampypsa/downscale/base.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
class ProportionalDownscaler(Downscaler):
    """Distribute coarse values to finer units in proportion to proxy shares."""

    def downscale(
        self,
        coarse: pd.DataFrame,
        proxy_shares: pd.DataFrame,
        *,
        coarse_id: str = "region",
        fine_id: str = "fine_id",
        share_col: str = "share",
        value_col: str = "value",
    ) -> pd.DataFrame:
        """Multiply each coarse value by its members' proxy shares.

        ``proxy_shares`` has columns ``[coarse_id, fine_id, share]`` (shares summing to 1
        within each ``coarse_id``); returns the coarse frame re-keyed to ``fine_id`` with
        ``value`` split by share.
        """
        merged = coarse.merge(proxy_shares, on=coarse_id, how="left")
        merged[value_col] = merged[value_col] * merged[share_col]
        return merged.drop(columns=[coarse_id, share_col]).rename(columns={fine_id: coarse_id})

downscale(coarse, proxy_shares, *, coarse_id='region', fine_id='fine_id', share_col='share', value_col='value')

Multiply each coarse value by its members' proxy shares.

proxy_shares has columns [coarse_id, fine_id, share] (shares summing to 1 within each coarse_id); returns the coarse frame re-keyed to fine_id with value split by share.

Source code in src/iampypsa/downscale/base.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
def downscale(
    self,
    coarse: pd.DataFrame,
    proxy_shares: pd.DataFrame,
    *,
    coarse_id: str = "region",
    fine_id: str = "fine_id",
    share_col: str = "share",
    value_col: str = "value",
) -> pd.DataFrame:
    """Multiply each coarse value by its members' proxy shares.

    ``proxy_shares`` has columns ``[coarse_id, fine_id, share]`` (shares summing to 1
    within each ``coarse_id``); returns the coarse frame re-keyed to ``fine_id`` with
    ``value`` split by share.
    """
    merged = coarse.merge(proxy_shares, on=coarse_id, how="left")
    merged[value_col] = merged[value_col] * merged[share_col]
    return merged.drop(columns=[coarse_id, share_col]).rename(columns={fine_id: coarse_id})