Skip to content

AssetCollection

An asset collection refers to groups of assets. Using the TZ platform you can access all assets within a specified geographic location.

To access data for assets and asset collections, you can use this Jupyter Notebook on Github.

Bases: DataFrame

An AssetCollection is an extension of a Pandas DataFrame.

It can be used in precisely the same way as a Pandas DataFrame but has a few extra useful constructors.

Parameters:

Name Type Description Default
_scope AssetcollectionScope | None

params for generating api query for pagination

 required
_page int | None

if generated from an API query, the current page of the query.

 required
Source code in tz/client/asset.py 
 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
class AssetCollection(pd.DataFrame):
    """An AssetCollection is an extension of a Pandas DataFrame.

    It can be used in precisely the same way as a Pandas DataFrame
    but has a few extra useful constructors.

    Args:
        _scope (schemas.AssetcollectionScope | None): params for generating api query for pagination
        _page (int | None): if generated from an API query, the current page of the query.
    """

    _scope: schemas.CollectionScope | None = None
    _page: int | None = None

    @property
    def _constructor(self):
        return AssetCollection

    @property
    def _constructor_sliced(self):
        return AssetCollectionRow

    @classmethod
    def from_parent_node(cls, node_id: str, sector: str = "power"):
        """Instantiate an AssetCollection from a parent node.

        Args:
            node_id (str): the id of the parent node to retieve assets for.
            sector (str): the name of the sector to retireve assets for.

        Returns:
            AssetCollection: A pandas-dataframe extension for TransitionZero assets.
        """

        obj = cls.from_assets(
            api.assets.get(parent_node_id=node_id, sector=sector)  # type: ignore[arg-type]
        )
        obj._scope = schemas.CollectionScope(parent_node_id=node_id, sector=sector)
        obj._page = 0
        return obj

    @classmethod
    def from_assets(cls, assets: List[Asset]):  # type: ignore[arg-type]
        """Instiate an AssetCollection from a list of Assets.
        Unpacks `AssetProperties` to dataframe columns.
        """
        # pd.DataFrame.from_records
        return cls.from_records([asset.unpack() for asset in assets])

    def next_page(self):
        """Paginate through assets. The Asset collection must have a `_scope`.

        Returns the next page of assets and concatenates them in-place to the current collection.
        """
        if not self._scope:
            raise ValueError("Cant iterate an unscoped AssetCollection")
        if self._scope.parent_node_id is None:
            raise ValueError("Cant iterate an AssetCollection without a parent id")
        new_collection = self.__class__.from_assets(
            api.assets.get(parent_node_id=self._scope.parent_node_id, page=self._page + 1)
        )
        self._page += 1

        self.__dict__.update(pd.concat([self, new_collection], ignore_index=True).__dict__)
        return len(new_collection)

    def to_assets(self):
        """Instantiate a list of Assets from an AssetCollection.
        Re-packs `AssetProperties` on assets from dataframe columns.
        """
        return [
            Asset(
                asset_properties=schemas.asset_sector_lookup[row["sector"]](**row),
                **row,
            )
            for idx, row in self.iterrows()
        ]

from_assets(assets) classmethod

Instiate an AssetCollection from a list of Assets. Unpacks AssetProperties to dataframe columns.

Source code in tz/client/asset.py 
111
112
113
114
115
116
117
@classmethod
def from_assets(cls, assets: List[Asset]):  # type: ignore[arg-type]
    """Instiate an AssetCollection from a list of Assets.
    Unpacks `AssetProperties` to dataframe columns.
    """
    # pd.DataFrame.from_records
    return cls.from_records([asset.unpack() for asset in assets])

from_parent_node(node_id, sector='power') classmethod

Instantiate an AssetCollection from a parent node.

Parameters:

Name Type Description Default
node_id str

the id of the parent node to retieve assets for.

 required
sector str

the name of the sector to retireve assets for.

 'power'

Returns:

Name Type Description
AssetCollection

A pandas-dataframe extension for TransitionZero assets.
Source code in tz/client/asset.py 
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
@classmethod
def from_parent_node(cls, node_id: str, sector: str = "power"):
    """Instantiate an AssetCollection from a parent node.

    Args:
        node_id (str): the id of the parent node to retieve assets for.
        sector (str): the name of the sector to retireve assets for.

    Returns:
        AssetCollection: A pandas-dataframe extension for TransitionZero assets.
    """

    obj = cls.from_assets(
        api.assets.get(parent_node_id=node_id, sector=sector)  # type: ignore[arg-type]
    )
    obj._scope = schemas.CollectionScope(parent_node_id=node_id, sector=sector)
    obj._page = 0
    return obj

next_page()

Paginate through assets. The Asset collection must have a _scope.

Returns the next page of assets and concatenates them in-place to the current collection.

Source code in tz/client/asset.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def next_page(self):
    """Paginate through assets. The Asset collection must have a `_scope`.

    Returns the next page of assets and concatenates them in-place to the current collection.
    """
    if not self._scope:
        raise ValueError("Cant iterate an unscoped AssetCollection")
    if self._scope.parent_node_id is None:
        raise ValueError("Cant iterate an AssetCollection without a parent id")
    new_collection = self.__class__.from_assets(
        api.assets.get(parent_node_id=self._scope.parent_node_id, page=self._page + 1)
    )
    self._page += 1

    self.__dict__.update(pd.concat([self, new_collection], ignore_index=True).__dict__)
    return len(new_collection)

to_assets()

Instantiate a list of Assets from an AssetCollection. Re-packs AssetProperties on assets from dataframe columns.

Source code in tz/client/asset.py 
136
137
138
139
140
141
142
143
144
145
146
def to_assets(self):
    """Instantiate a list of Assets from an AssetCollection.
    Re-packs `AssetProperties` on assets from dataframe columns.
    """
    return [
        Asset(
            asset_properties=schemas.asset_sector_lookup[row["sector"]](**row),
            **row,
        )
        for idx, row in self.iterrows()
    ]