Skip to content

ClusteringAccessor 

ClusteringAccessor(n: Network)

Clustering accessor for clustering a network spatially and temporally.

Clustering

Referenced by: Returned by: Used by:

Attributes:

pypsa.Network.cluster.spatial property 

spatial: SpatialClusteringAccessor

Access spatial clustering methods.

Returns:

Examples:

>>> n.cluster.spatial.busmap_by_kmeans(weighting, 50)
>>> n.cluster.spatial.cluster_by_busmap(busmap)
>>> n.cluster.spatial.cluster_by_kmeans(weighting, 50)

pypsa.Network.cluster.temporal property 

temporal: TemporalClusteringAccessor

Access temporal clustering methods.

Returns:

Examples:

>>> n.cluster.temporal.resample("3h")
>>> n.cluster.temporal.downsample(4)
>>> n.cluster.temporal.segment(100)

SpatialClusteringAccessor 

SpatialClusteringAccessor(n: Network)


              flowchart TD
              pypsa.clustering.SpatialClusteringAccessor[SpatialClusteringAccessor]
              pypsa.clustering.spatial.SpatialClusteringMixin[SpatialClusteringMixin]

                              pypsa.clustering.spatial.SpatialClusteringMixin --> pypsa.clustering.SpatialClusteringAccessor
                


              click pypsa.clustering.SpatialClusteringAccessor href "" "pypsa.clustering.SpatialClusteringAccessor"
              click pypsa.clustering.spatial.SpatialClusteringMixin href "" "pypsa.clustering.spatial.SpatialClusteringMixin"

Spatial clustering accessor for clustering a network spatially.

Clustering

Returned by:

Methods:

pypsa.clustering.SpatialClusteringAccessor.busmap_by_greedy_modularity 

busmap_by_greedy_modularity(n_clusters: int, buses_i: Index | None = None) -> Series

Create a busmap according to Clauset-Newman-Moore greedy modularity maximization.

See [CNM2004_1]_ for more details.

Parameters:

  • n_clusters (int) –

    Final number of clusters desired.

  • buses_i (Index | None, default: None ) –

    Subset of buses to cluster. If None, all buses are considered.

Returns:

  • busmap ( Series ) –

    Mapping of n.buses to clusters (indexed by non-negative integers).

References

[CNM2004_1] Clauset, A., Newman, M. E., & Moore, C. "Finding community structure in very large networks." Physical Review E 70(6), 2004.

pypsa.clustering.SpatialClusteringAccessor.busmap_by_hac 

busmap_by_hac(n_clusters: int, buses_i: Index | None = None, branch_components: Collection[str] | None = None, feature: DataFrame | None = None, affinity: str | Callable = 'euclidean', linkage: str = 'ward', **kwargs: Any) -> Series

Create a busmap according to Hierarchical Agglomerative Clustering.

Parameters:

  • n_clusters (int) –

    Final number of clusters desired.

  • buses_i (Index | None, default: None ) –

    Subset of buses to cluster. If None, all buses are considered.

  • branch_components (Collection[str] | None, default: None ) –

    Subset of all branch_components in the network. If None, all branch_components are considered.

  • feature (DataFrame | None, default: None ) –

    Feature to be considered for the clustering. The DataFrame must be indexed with buses_i. If None, all buses have the same similarity.

  • affinity (str | Callable, default: 'euclidean' ) –

    Metric used to compute the linkage. Can be "euclidean", "l1", "l2", "manhattan", "cosine", or "precomputed". If linkage is "ward", only "euclidean" is accepted. If "precomputed", a distance matrix (instead of a similarity matrix) is needed as input for the fit method.

  • linkage (str, default: 'ward' ) –

    Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. - 'ward' minimizes the variance of the clusters being merged. - 'average' uses the average of the distances of each observation of the two sets. - 'complete' or 'maximum' linkage uses the maximum distances between all observations of the two sets. - 'single' uses the minimum of the distances between all observations of the two sets.

  • kwargs (Any, default: {} ) –

    Any remaining arguments to be passed to Hierarchical Clustering (e.g. memory, connectivity).

Returns:

  • busmap ( Series ) –

    Mapping of n.buses to clusters (indexed by non-negative integers).

pypsa.clustering.SpatialClusteringAccessor.busmap_by_kmeans 

busmap_by_kmeans(bus_weightings: Series, n_clusters: int, buses_i: Index | None = None, **kwargs: Any) -> Series

Create a bus map from the clustering of buses in space with a weighting.

Parameters:

  • bus_weightings (Series) –

    Series of integer weights for buses, indexed by bus names.

  • n_clusters (int) –

    Final number of clusters desired.

  • buses_i (None | Index, default: None ) –

    If not None (default), subset of buses to cluster.

  • kwargs (Any, default: {} ) –

    Any remaining arguments to be passed to KMeans (e.g. n_init, n_jobs).

Returns:

  • busmap ( Series ) –

    Mapping of n.buses to k-means clusters (indexed by non-negative integers).

pypsa.clustering.SpatialClusteringAccessor.cluster_by_busmap 

cluster_by_busmap(busmap: dict, with_time: bool = True, line_length_factor: float = 1.0, aggregate_generators_weighted: bool = False, aggregate_one_ports: dict | None = None, aggregate_generators_carriers: Iterable | None = None, scale_link_capital_costs: bool = True, bus_strategies: dict | None = None, one_port_strategies: dict | None = None, generator_strategies: dict | None = None, line_strategies: dict | None = None, aggregate_generators_buses: Iterable | None = None, custom_line_groupers: list | None = None) -> Network

Cluster the network spatially by busmap.

This function calls get_clustering_from_busmap internally. For more information, see the documentation of that function.

Returns:

pypsa.clustering.SpatialClusteringAccessor.cluster_by_greedy_modularity 

cluster_by_greedy_modularity(n_clusters: int, buses_i: Index | None = None, line_length_factor: float = 1.0) -> Network

Cluster the network using Clauset-Newman-Moore greedy modularity maximization.

See [CNM2004_2]_ for more details.

Parameters:

  • n_clusters (int) –

    Final number of clusters desired.

  • buses_i (Index | None, default: None ) –

    Subset of buses to cluster. If None, all buses are considered.

  • line_length_factor (float, default: 1.0 ) –

    Factor to multiply the spherical distance between two new buses to get new line lengths.

Returns:

  • Network –

    The clustered network.

References

[CNM2004_2] Clauset, A., Newman, M. E., & Moore, C. "Finding community structure in very large networks." Physical Review E 70(6), 2004.

pypsa.clustering.SpatialClusteringAccessor.cluster_by_hac 

cluster_by_hac(n_clusters: int, buses_i: Index | None = None, branch_components: Collection[str] | None = None, feature: DataFrame | None = None, affinity: str | Callable = 'euclidean', linkage: str = 'ward', line_length_factor: float = 1.0, **kwargs: Any) -> Network

Cluster the network using Hierarchical Agglomerative Clustering.

Parameters:

  • n_clusters (int) –

    Final number of clusters desired.

  • buses_i (Index | None, default: None ) –

    Subset of buses to cluster. If None, all buses are considered.

  • branch_components (Collection[str] | None, default: None ) –

    Subset of all branch_components in the network.

  • feature (DataFrame | None, default: None ) –

    Feature to be considered for the clustering. The DataFrame must be indexed with buses_i. If None, all buses have the same similarity.

  • affinity (str | Callable, default: 'euclidean' ) –

    Metric used to compute the linkage. Can be "euclidean", "l1", "l2", "manhattan", "cosine", or "precomputed". If linkage is "ward", only "euclidean" is accepted. If "precomputed", a distance matrix (instead of a similarity matrix) is needed as input for the fit method.

  • linkage (str, default: 'ward' ) –

    Which linkage criterion to use. The linkage criterion determines which distance to use between sets of observation. The algorithm will merge the pairs of cluster that minimize this criterion. - 'ward' minimizes the variance of the clusters being merged. - 'average' uses the average of the distances of each observation of the two sets. - 'complete' or 'maximum' linkage uses the maximum distances between all observations of the two sets. - 'single' uses the minimum of the distances between all observations of the two sets.

  • line_length_factor (float, default: 1.0 ) –

    Factor to multiply the spherical distance between two new buses in order to get new line lengths.

  • kwargs (Any, default: {} ) –

    Any remaining arguments to be passed to Hierarchical Clustering (e.g. memory, connectivity).

Returns:

  • Network –

    The clustered network.

pypsa.clustering.SpatialClusteringAccessor.cluster_by_kmeans 

cluster_by_kmeans(bus_weightings: Series, n_clusters: int, line_length_factor: float = 1.0, **kwargs: Any) -> Network

Cluster the network according to k-means clustering of the buses.

Buses can be weighted by an integer in the series bus_weightings.

Note that this clustering method completely ignores the branches of the network.

Parameters:

  • bus_weightings (Series) –

    Series of integer weights for buses, indexed by bus names.

  • n_clusters (int) –

    Final number of clusters desired.

  • line_length_factor (float, default: 1.0 ) –

    Factor to multiply the spherical distance between new buses in order to get new line lengths.

  • kwargs (Any, default: {} ) –

    Any remaining arguments to be passed to KMeans (e.g. n_init, n_jobs)

Returns:

  • Network –

    The clustered network.

pypsa.clustering.SpatialClusteringAccessor.get_clustering_from_busmap 

get_clustering_from_busmap(busmap: dict, with_time: bool = True, line_length_factor: float = 1.0, aggregate_generators_weighted: bool = False, aggregate_one_ports: dict | None = None, aggregate_generators_carriers: Iterable | None = None, scale_link_capital_costs: bool = True, bus_strategies: dict | None = None, one_port_strategies: dict | None = None, generator_strategies: dict | None = None, line_strategies: dict | None = None, aggregate_generators_buses: Iterable | None = None, custom_line_groupers: list | None = None) -> Clustering

Get a clustering result from a busmap.

Referenced by:

TemporalClusteringAccessor 

TemporalClusteringAccessor(n: Network)


              flowchart TD
              pypsa.clustering.TemporalClusteringAccessor[TemporalClusteringAccessor]
              pypsa.clustering.temporal.TemporalClusteringMixin[TemporalClusteringMixin]

                              pypsa.clustering.temporal.TemporalClusteringMixin --> pypsa.clustering.TemporalClusteringAccessor
                


              click pypsa.clustering.TemporalClusteringAccessor href "" "pypsa.clustering.TemporalClusteringAccessor"
              click pypsa.clustering.temporal.TemporalClusteringMixin href "" "pypsa.clustering.temporal.TemporalClusteringMixin"

Temporal clustering accessor for clustering a network temporally.

Provides methods to reduce temporal resolution of networks while preserving total modeled hours through snapshot weighting adjustments.

Examples:

>>> n.cluster.temporal.resample("3h")
>>> n.cluster.temporal.downsample(4)
>>> n.cluster.temporal.segment(100)
Returned by:

Methods:

pypsa.clustering.TemporalClusteringAccessor.downsample 

downsample(stride: int) -> Network

Select every Nth snapshot as representative.

Weightings are scaled by stride to preserve total modeled hours.

Parameters:

  • stride (int) –

    Select every stride-th snapshot.

Returns:

  • Network –

    The downsampled network.

Examples:

>>> m = n.cluster.temporal.downsample(4)

pypsa.clustering.TemporalClusteringAccessor.from_snapshot_map 

from_snapshot_map(snapshot_map: Series | DataFrame, *, aggregation_rules: dict[str, str] | None = None) -> Network

Apply pre-computed temporal aggregation mapping.

Parameters:

  • snapshot_map (Series or DataFrame) –

    Mapping from original snapshots to aggregated snapshots. If DataFrame, must have 'snapshot' index and columns for weightings.

  • aggregation_rules (dict, default: None ) –

    Override default aggregation per attribute.

Returns:

  • Network –

    The aggregated network.

pypsa.clustering.TemporalClusteringAccessor.get_downsample_result 

get_downsample_result(stride: int) -> TemporalClustering

Get full TemporalClustering result from downsample.

Returns the full result including both the clustered network and the snapshot mapping.

Parameters:

  • stride (int) –

    Select every stride-th snapshot.

Returns:

  • TemporalClustering –

    Result with downsampled network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.get_from_snapshot_map_result 

get_from_snapshot_map_result(snapshot_map: Series | DataFrame, *, aggregation_rules: dict[str, str] | None = None) -> TemporalClustering

Get full TemporalClustering result from from_snapshot_map.

Returns the full result including both the clustered network and the snapshot mapping.

Parameters:

  • snapshot_map (Series or DataFrame) –

    Mapping from original snapshots to aggregated snapshots. If DataFrame, must have 'snapshot' index and columns for weightings.

  • aggregation_rules (dict, default: None ) –

    Override default aggregation per attribute.

Returns:

  • TemporalClustering –

    Result with aggregated network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.get_resample_result 

get_resample_result(offset: str, *, drop_leap_day: bool = False, aggregation_rules: dict[str, str] | None = None) -> TemporalClustering

Get full TemporalClustering result from resample.

Returns the full result including both the clustered network and the snapshot mapping. Use this when you need the snapshot_map for disaggregation or debugging.

Parameters:

  • offset (str) –

    Pandas offset string (e.g., "3h", "6h", "24h").

  • drop_leap_day (bool, default: False ) –

    Transfer Feb 29 weights to March 1.

  • aggregation_rules (dict, default: None ) –

    Override default aggregation per attribute.

Returns:

  • TemporalClustering –

    Result with clustered network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.get_segment_result 

get_segment_result(num_segments: int, *, solver: str = 'highs', exclude_attrs: list[str] | None = None, aggregation_rules: dict[str, str] | None = None) -> TemporalClustering

Get full TemporalClustering result from segment.

Returns the full result including both the clustered network and the snapshot mapping.

Parameters:

  • num_segments (int) –

    Target number of segments.

  • solver (str, default: "highs" ) –

    MIP solver for time clustering.

  • exclude_attrs (list, default: None ) –

    Attributes to exclude from clustering (default: ["e_min_pu"]).

  • aggregation_rules (dict, default: None ) –

    Override default aggregation per attribute.

Returns:

  • TemporalClustering –

    Result with segmented network and snapshot mapping.

pypsa.clustering.TemporalClusteringAccessor.resample 

resample(offset: str, *, drop_leap_day: bool = False, aggregation_rules: dict[str, str] | None = None) -> Network

Resample network to coarser temporal resolution.

Parameters:

  • offset (str) –

    Pandas offset string (e.g., "3h", "6h", "24h").

  • drop_leap_day (bool, default: False ) –

    Transfer Feb 29 weights to March 1.

  • aggregation_rules (dict, default: None ) –

    Override default aggregation per attribute.

Returns:

  • Network –

    The resampled network.

Note

This is not an inplace operation. Returns a new network.

Examples:

>>> m = n.cluster.temporal.resample("3h")

pypsa.clustering.TemporalClusteringAccessor.segment 

segment(num_segments: int, *, solver: str = 'highs', exclude_attrs: list[str] | None = None, aggregation_rules: dict[str, str] | None = None) -> Network

Cluster time series into variable-duration segments using TSAM.

Parameters:

  • num_segments (int) –

    Target number of segments.

  • solver (str, default: "highs" ) –

    MIP solver for time clustering.

  • exclude_attrs (list, default: None ) –

    Attributes to exclude from clustering (default: ["e_min_pu"]).

  • aggregation_rules (dict, default: None ) –

    Override default aggregation per attribute.

Returns:

  • Network –

    The segmented network.

Note

Requires tsam package: pip install tsam