Attribute¶

Overview¶

Attribute stores values, metadata, units, and provenance for one model attribute.

Use Cases¶

Set and validate default values for element attributes.
Manage tabular and yearly varying data with source information.

Examples¶

from zen_creator import Attribute

# Usually created through element classes.
class MyAttribute(Attribute):
    pass

Summary

zen_creator.Attribute.__init__

Initialize an Attribute.

Constructors

Attribute.__init__(name: str, element: Element, default_value: DefaultValue = None, unit: str | None = None, base_technology: str | None = None, df: DataFrame | None = None, year_specific_dfs: dict[int, DataFrame] | None = None, yearly_variations_df: DataFrame | None = None, sources: list[SourceInformation] | None = None)¶

Initialize an Attribute.

Parameters:

name – The name of the attribute.
element – The element this attribute belongs to.
default_value – Default value for the attribute (optional).
unit – The unit of measurement for this attribute (optional).
base_technology – Base technology for retrofit_flow_coupling_factor (optional).
df – Time-series data as a pandas DataFrame or Series (optional).
year_specific_dfs – Year-specific data frames (optional).
yearly_variations_df – Yearly variation factors (optional).
sources – Ordered source information entries for this attribute (optional).

Member Reference

class zen_creator.Attribute(name: str, element: Element, default_value: DefaultValue = None, unit: str | None = None, base_technology: str | None = None, df: DataFrame | None = None, year_specific_dfs: dict[int, DataFrame] | None = None, yearly_variations_df: DataFrame | None = None, sources: list[SourceInformation] | None = None)

Bases: object

Represents a single attribute of an energy system element.

An attribute can have default values, time-series data, yearly variations, and source information. It includes comprehensive validation to ensure data integrity.

name: The name of the attribute.

element: The element this attribute belongs to.

add_source(source: SourceInformation) → None

Append a source entry while preserving insertion order.

Parameters:: source – Source information to append.

property base_technology: str | None: Set the base technology for retrofit_flow_coupling_factor.

default_to_dict() → dict | list[dict]

Convert the default value and unit to a dictionary representation.

Returns:: Dictionary with ‘default_value’ and ‘unit’ keys.
Raises:: ValueError – If the default value type is not serializable.

property default_value: float | list | None: Get the default value of this attribute.

property df: DataFrame | Series | None: Get the time-series data.

overwrite_from_existing_model(existing_element_path: Path) → None

Load attribute values from an existing model directory.

This method loads default values from attributes.json and time-series data from CSV files in the existing model directory.

Parameters:: existing_element_path – Path to the existing element directory.

save_data(folder_path: str, element_name: str) → None

Save time-series data to a CSV file.

Parameters:

folder_path – Directory where the file will be saved.
element_name – Name of the element (for logging purposes).

Set multiple attribute properties at once.

This is a convenience method for setting multiple properties in a chain. The source parameter is mandatory. It should contain a SourceInformation object that includes a description of changes and the corresponding Dataset/DatasetCollection MetaData to ensure proper source tracking.

Parameters:

default_value – Default value for the attribute.
unit – Unit of measurement.
df – Time-series data.
yearly_variations_df – Yearly variation factors.
source – Source information to append to the ordered source list.

Returns:

Self for method chaining.

property sources: list[SourceInformation]: Get the ordered source information entries.

sources_to_str() → str

Serialize the ordered sources into a readable numbered string.

Returns:: A multi-line string where each source is prefixed with its insertion order so the sequence of additions remains visible.

property unit: str | None: Get the unit of measurement.

property year_specific_dfs: dict[int, DataFrame | Series]: Get the year-specific time series data.

property yearly_variations_df: DataFrame | Series | None: Get the yearly variations data.