""" .. module:: skrf.networkSet ======================================== networkSet (:mod:`skrf.networkSet`) ======================================== Provides a class representing an un-ordered set of n-port microwave networks. Frequently one needs to make calculations, such as mean or standard deviation, on an entire set of n-port networks. To facilitate these calculations the :class:`NetworkSet` class provides convenient ways to make such calculations. Another usage is to interpolate a set of Networks which depend of an parameter (like a knob, or a geometrical parameter). The results are returned in :class:`~skrf.network.Network` objects, so they can be plotted and saved in the same way one would do with a :class:`~skrf.network.Network`. The functionality in this module is provided as methods and properties of the :class:`NetworkSet` Class. NetworkSet Class ================ .. autosummary:: :toctree: generated/ NetworkSet NetworkSet Utilities ==================== .. autosummary:: :toctree: generated/ func_on_networks getset """ from __future__ import annotations import zipfile from collections.abc import Mapping from io import BytesIO from numbers import Number from pathlib import Path from typing import Any, TextIO import numpy as np import pandas as pd from scipy.interpolate import interp1d from . import mathFunctions as mf from .constants import NumberLike, PrimaryPropertiesT from .network import COMPONENT_FUNC_DICT, PRIMARY_PROPERTIES, Frequency, Network from .util import copy_doc, now_string_2_dt try: from numpy.typing import ArrayLike except ImportError: ArrayLike = Any from . import plotting as skrf_plt class NetworkSet: """ A set of Networks. This class allows functions on sets of Networks, such as mean or standard deviation, to be calculated conveniently. The results are returned in :class:`~skrf.network.Network` objects, so that they may be plotted and saved in like :class:`~skrf.network.Network` objects. This class also provides methods which can be used to plot uncertainty bounds for a set of :class:`~skrf.network.Network`. The names of the :class:`NetworkSet` properties are generated dynamically upon initialization, and thus documentation for individual properties and methods is not available. However, the properties do follow the convention:: >>> my_network_set.function_name_network_property_name For example, the complex average (mean) :class:`~skrf.network.Network` for a :class:`NetworkSet` is:: >>> my_network_set.mean_s This accesses the property 's', for each element in the set, and **then** calculates the 'mean' of the resultant set. The order of operations is important. Results are returned as :class:`~skrf.network.Network` objects, so they may be plotted or saved in the same way as for :class:`~skrf.network.Network` objects:: >>> my_network_set.mean_s.plot_s_mag() >>> my_network_set.mean_s.write_touchstone('mean_response') If you are calculating functions that return scalar variables, then the result is accessible through the Network property .s_re. For example:: >>> std_s_deg = my_network_set.std_s_deg This result would be plotted by:: >>> std_s_deg.plot_s_re() The operators, properties, and methods of NetworkSet object are dynamically generated by private methods * :func:`~NetworkSet.__add_a_operator` * :func:`~NetworkSet.__add_a_func_on_property` * :func:`~NetworkSet.__add_a_element_wise_method` * :func:`~NetworkSet.__add_a_plot_uncertainty` thus, documentation on the individual methods and properties are not available. """ def __init__(self, ntwk_set: list | dict = None, name: str = None): """ Initialize for NetworkSet. Parameters ---------- ntwk_set : list of :class:`~skrf.network.Network` objects the set of :class:`~skrf.network.Network` objects name : string the name of the NetworkSet, given to the Networks returned from properties of this class. """ if ntwk_set is None: ntwk_set = [] if not isinstance(ntwk_set, (list, dict)): raise ValueError('NetworkSet requires a list as argument') # dict is authorized for convenience # but if a dict is passed instead of a list -> list if isinstance(ntwk_set, dict): ntwk_set = list(ntwk_set.values()) # did they pass a list of Networks? if not all([isinstance(ntwk, Network) for ntwk in ntwk_set]): raise(TypeError('input must be list of Network types')) # do all Networks have the same # ports? if len (set([ntwk.number_of_ports for ntwk in ntwk_set])) > 1: raise(ValueError('All elements in list of Networks must have same number of ports')) # is all frequency information the same? if not np.all([(ntwk_set[0].frequency == ntwk.frequency) for ntwk in ntwk_set]): raise(ValueError('All elements in list of Networks must have same frequency information')) ## initialization # we are good to go self.ntwk_set: list[Network] = ntwk_set self.name = name # extract the dimensions of the set try: self.dims = self.ntwk_set[0].params.keys() except (AttributeError, IndexError): # .params is None self.dims = dict() # extract the coordinates of the set try: self.coords = {p: [] for p in self.dims} for k in self.ntwk_set: for p in self.dims: self.coords[p].append(k.params[p]) # keep only unique terms for p in self.coords.keys(): self.coords[p] = list(set(self.coords[p])) except TypeError: # .params is None self.coords = None # create list of network properties, which we use to dynamically # create a statistical properties of this set network_property_list = [k+'_'+l \ for k in PRIMARY_PROPERTIES \ for l in COMPONENT_FUNC_DICT.keys()] + \ ['passivity','s'] # dynamically generate properties. this is slick. max, min = np.max, np.min max.__name__ = 'max' min.__name__ = 'min' for network_property_name in network_property_list: for func in [np.mean, np.std, max, min]: self.__add_a_func_on_property(func, network_property_name) if 'db' not in network_property_name:# != 's_db' and network_property_name != 's': # db uncertainty requires a special function call see # plot_uncertainty_bounds_s_db self.__add_a_plot_uncertainty(network_property_name) self.__add_a_plot_minmax(network_property_name) self.__add_a_element_wise_method('plot_'+network_property_name) self.__add_a_element_wise_method('plot_s_db') self.__add_a_element_wise_method('plot_s_db_time') for network_method_name in \ ['write_touchstone','interpolate','plot_s_smith']: self.__add_a_element_wise_method(network_method_name) for operator_name in \ ['__pow__','__floordiv__','__mul__','__truediv__','__add__','__sub__']: self.__add_a_operator(operator_name) @classmethod def from_zip(cls, zip_file_name: str | Path, sort_filenames: bool = True, *args, **kwargs): r""" Create a NetworkSet from a zipfile of touchstones. Parameters ---------- zip_file_name : string or Path name of zipfile sort_filenames: Boolean sort the filenames in the zip file before constructing the NetworkSet \*args, \*\*kwargs : arguments passed to NetworkSet constructor Examples -------- >>> import skrf as rf >>> my_set = rf.NetworkSet.from_zip('myzip.zip') """ z = zipfile.ZipFile(zip_file_name) filename_list = z.namelist() ntwk_list = [] if sort_filenames: filename_list.sort() for filename in filename_list: # try/except block in case not all files are touchstones try: # Ascii files (Touchstone, etc) n = Network.zipped_touchstone(filename, z) ntwk_list.append(n) continue except Exception: pass try: # Binary files (pickled Network) fileobj = BytesIO(z.open(filename).read()) fileobj.name = filename n = Network(fileobj) ntwk_list.append(n) continue except Exception: pass return cls(ntwk_list) @classmethod def from_dir(cls, dir: str | Path = '.', *args, **kwargs): r""" Create a NetworkSet from a directory containing Networks. This just calls :: rf.NetworkSet(rf.read_all_networks(dir), *args, **kwargs) Parameters ---------- dir : str or Path directory containing Network files. \*args, \*\*kwargs : passed to NetworkSet constructor Examples -------- >>> my_set = rf.NetworkSet.from_dir('./data/') """ from .io.general import read_all_networks return cls(read_all_networks(dir), *args, **kwargs) @classmethod def from_s_dict(cls, d: dict, frequency: Frequency, *args, **kwargs): r""" Create a NetworkSet from a dictionary of s-parameters The resultant elements of the NetworkSet are named by the keys of the dictionary. Parameters ------------- d : dict dictionary of s-parameters data. values of this should be :class:`numpy.ndarray` assignable to :attr:`skrf.network.Network.s` frequency: :class:`~skrf.frequency.Frequency` object frequency assigned to each network \*args, \*\*kwargs : passed to Network.__init__ for each key/value pair of d Returns ---------- ns : NetworkSet See Also ---------- NetworkSet.to_s_dict """ return cls([Network(s=d[k], frequency=frequency, name=k, **kwargs) for k in d]) @classmethod def from_mdif(cls, file: str | Path | TextIO) -> NetworkSet: """ Create a NetworkSet from a MDIF file. Parameters ---------- file : str, Path, file-object MDIF file to load Returns ------- ns : :class: `~skrf.networkSet.NetworkSet` See Also -------- Mdif : MDIF Object write_mdif : Convert a NetworkSet to a Generalized MDIF file. """ from .io import Mdif return Mdif(file).to_networkset() @classmethod def from_citi(cls, file: str | Path | TextIO) -> NetworkSet: """ Create a NetworkSet from a CITI file. Parameters ---------- file : str, Path, or file-object CITI file to load Returns ------- ns : :class: `~skrf.networkSet.NetworkSet` See Also -------- Citi """ from .io import Citi return Citi(file).to_networkset() def __add_a_operator(self, operator_name): """ Add an operator method to the NetworkSet. this is made to take either a Network or a NetworkSet. if a Network is passed to the operator, each element of the set will operate on the Network. If a NetworkSet is passed to the operator, and is the same length as self. then it will operate element-to-element like a dot-product. """ def operator_func(self, other): if isinstance(other, NetworkSet): if len(other) != len(self): raise(ValueError('Network sets must be of same length to be cascaded')) return NetworkSet([ getattr(self.ntwk_set[k], operator_name)(other.ntwk_set[k]) for k in range(len(self)) ]) elif isinstance(other, Network): return NetworkSet([getattr(ntwk, operator_name)(other) for ntwk in self.ntwk_set]) else: raise(TypeError('NetworkSet operators operate on either Network, or NetworkSet types')) setattr(self.__class__,operator_name,operator_func) def __str__(self): """ """ return f'{len(self.ntwk_set)}-Networks NetworkSet: '+self.ntwk_set.__str__() def __repr__(self): return self.__str__() def __getitem__(self, key): """ Return an element of the network set. """ if isinstance(key, str): # if they pass a string then slice each network in this set return NetworkSet([k[key] for k in self.ntwk_set], name = self.name) else: return self.ntwk_set[key] def __len__(self) -> int: """ Return the number of Networks in a NetworkSet. Return ------ len: int Number of Networks in a NetworkSet """ return len(self.ntwk_set) def __eq__(self, other: NetworkSet) -> bool: """ Compare the NetworkSet with another NetworkSet. Two NetworkSets are considered equal of their Networks are all equals (in the same order) Returns ------- is_equal: bool """ # of course they should have equal lengths if len(self) != len(other): return False # compare all networks in the order of the list # return False as soon as 2 networks are different for (ntwk, ntwk_other) in zip(self.ntwk_set, other): if ntwk != ntwk_other: return False return True def __add_a_element_wise_method(self, network_method_name: str): def func(self, *args, **kwargs): return self.element_wise_method(network_method_name, *args, **kwargs) setattr(self.__class__,network_method_name,func) def __add_a_func_on_property(self, func, network_property_name: str): """ Dynamically add a property to this class (NetworkSet). this is mostly used internally to generate all of the classes properties. Parameters ---------- func: a function to be applied to the network_property across the first axis of the property's output network_property_name: str a property of the Network class, which must have a matrix output of shape (f, n, n) example ------- >>> my_ntwk_set.add_a_func_on_property(mean, 's') """ def fget(self): return fon(self.ntwk_set, func, network_property_name, name=self.name) setattr(self.__class__,func.__name__+'_'+network_property_name,\ property(fget)) def __add_a_plot_uncertainty(self, network_property_name: str): """ Add a plot uncertainty to a Network property. Parameter --------- network_property_name: str A property of the Network class, which must have a matrix output of shape (f, n, n) Parameter --------- >>> my_ntwk_set.__add_a_plot_uncertainty('s') """ def plot_func(self,*args, **kwargs): self.plot_uncertainty_bounds_component(network_property_name, *args,**kwargs) setattr(self.__class__,'plot_uncertainty_bounds_'+\ network_property_name,plot_func) setattr(self.__class__,'plot_ub_'+\ network_property_name,plot_func) def __add_a_plot_minmax(self, network_property_name: str): """ Parameter --------- network_property_name: str A property of the Network class, which must have a matrix output of shape (f, n, n) Example ------- >>> my_ntwk_set.__add_a_plot_minmax('s') """ def plot_func(self,*args, **kwargs): self.plot_minmax_bounds_component(network_property_name, *args,**kwargs) setattr(self.__class__,'plot_minmax_bounds_'+\ network_property_name,plot_func) setattr(self.__class__,'plot_mm_'+\ network_property_name,plot_func) def to_dict(self) -> dict: """ Return a dictionary representation of the NetworkSet. Return ------ d : dict The returned dictionary has the Network names for keys, and the Networks as values. """ return {k.name: k for k in self.ntwk_set} def to_s_dict(self): """ Converts a NetworkSet to a dictionary of s-parameters. The resultant keys of the dictionary are the names of the Networks in NetworkSet Returns ------- s_dict : dictionary contains s-parameters in the form of complex numpy arrays See Also -------- NetworkSet.from_s_dict """ d = self.to_dict() for k in d: d[k] = d[k].s return d def element_wise_method(self, network_method_name: str, *args, **kwargs) -> NetworkSet: """ Call a given method of each element and returns the result as a new NetworkSet if the output is a Network. Parameter --------- network_property_name: str A property of the Network class, which must have a matrix output of shape (f, n, n) Return ------ ns: :class: `~skrf.networkSet.NetworkSet` """ output = [getattr(ntwk, network_method_name)(*args, **kwargs) for ntwk in self.ntwk_set] if isinstance(output[0],Network): return NetworkSet(output) else: return output def copy(self) -> NetworkSet: """ Copy each network of the network set. Return ------ ns: :class: `~skrf.networkSet.NetworkSet` """ return NetworkSet([k.copy() for k in self.ntwk_set]) def sort(self, key=lambda x: x.name, inplace: bool = True, **kwargs) -> None | NetworkSet: r""" Sort this network set. Parameters ---------- key: inplace: bool Sort the NetworkSet object directly if True, return the sorted NetworkSet if False. Default is True. \*\*kwargs : dict keyword args passed to builtin sorted acting on self.ntwk_set Return ------ ns: None if inplace=True, NetworkSet if False Examples -------- >>> ns = rf.NetworkSet.from_dir('mydir') >>> ns.sort() Sort by other property: >>> ns.sort(key= lambda x: x.voltage) Returns a new NetworkSet: >>> sorted_ns = ns.sort(inplace=False) """ sorted_ns = sorted(self.ntwk_set, key = key, **kwargs) if inplace: self.ntwk_set = sorted_ns else: return sorted_ns def rand(self, n: int = 1, rng: None | np.random.Generator = None): """ Return `n` random samples from this NetworkSet. Parameters ---------- n : int number of samples to return (default is 1) rng : :class:`numpy.random.Generator` or None override the global :mod:`numpy` random number generator, useful for multi-threaded programs since :func:`skrf.mathFunctions.set_rand_rng` is not thread-safe. """ if rng is None: rng = mf.rand_rng() idx = rng.randint(0,len(self), n) out = [self.ntwk_set[k] for k in idx] if n ==1: return out[0] else: return out def filter(self, s: str) -> NetworkSet: """ Filter NetworkSet based on a string in `Network.name`. Notes ----- This is just `NetworkSet([k for k in self if s in k.name])` Parameters ---------- s: str string contained in network elements to be filtered Returns -------- ns : :class: `skrf.NetworkSet` Examples ----------- >>> ns.filter('monday') """ return NetworkSet([k for k in self if s in k.name]) def scalar_mat(self, param: str = 's') -> np.ndarray: """ Return a scalar ndarray representing `param` data vs freq and element idx. Output is a 3d array with axes (freq, ns_index, port/ri). ports is a flattened re/im components of port index (`len = 2*nports**2`). Parameter --------- param : str name of the parameter to export. Default is 's'. Return ------ x : :class: np.ndarray """ ntwk = self[0] nfreq = len(ntwk) # x will have the axes (frequency, observations, ports) x = np.array([[mf.flatten_c_mat(getattr(k, param)[f]) \ for k in self] for f in range(nfreq)]) return x def cov(self, **kw) -> np.ndarray: """ Covariance matrix. shape of output will be (nfreq, 2*nports**2, 2*nports**2) """ smat=self.scalar_mat(**kw) return np.array([np.cov(k.T) for k in smat]) @property def mean_s_db(self) -> Network: """ Return Network of mean magnitude in dB. Return ------ ntwk : :class: `~skrf.network.Network` Network of the mean magnitude in dB Note ---- The mean is taken on the magnitude before converted to db, so `magnitude_2_db(mean(s_mag))` which is NOT the same as `mean(s_db)` """ ntwk = self.mean_s_mag ntwk.s = ntwk.s_db return ntwk @property def std_s_db(self) -> Network: """ Return the Network of the standard deviation magnitude in dB. Return ------ ntwk : :class: `~skrf.network.Network` Network of the mean magnitude in dB Note ---- The standard deviation is taken on the magnitude before converted to db, so `magnitude_2_db(std(s_mag))` which is NOT the same as `std(s_db)` """ ntwk= self.std_s_mag ntwk.s = ntwk.s_db return ntwk @property def inv(self) -> NetworkSet: """ Return the NetworkSet of inverted Networks (Network.inv()). Returns ------- ntwkSet : :class: `~skrf.networkSet.NetworkSet` NetworkSet of inverted Networks """ return NetworkSet( [ntwk.inv for ntwk in self.ntwk_set]) def add_polar_noise(self, ntwk: Network) -> Network: """ Parameters ---------- ntwk : :class: `~skrf.network.Network` Returns ------- ntwk : :class: `~skrf.network.Network` """ from numpy import frompyfunc from scipy import stats def gimme_norm(x): return stats.norm(loc=0, scale=x).rvs(1)[0] ugimme_norm = frompyfunc(gimme_norm,1,1) s_deg_rv = np.array(map(ugimme_norm, self.std_s_deg.s_re), dtype=float) s_mag_rv = np.array(map(ugimme_norm, self.std_s_mag.s_re), dtype=float) mag = ntwk.s_mag + s_mag_rv deg = ntwk.s_deg + s_deg_rv ntwk.s = mag * np.exp(1j*np.pi/180*deg) return ntwk def set_wise_function(self, func, a_property: str, *args, **kwargs): """ Calls a function on a specific property of the Networks in this NetworkSet. Parameters ---------- func : callable a_property : str Example ------- >>> my_ntwk_set.set_wise_func(mean,'s') """ return fon(self.ntwk_set, func, a_property, *args, **kwargs) def uncertainty_ntwk_triplet(self, attribute: PrimaryPropertiesT, n_deviations: int = 3) -> tuple( Network, Network, Network ): """ Return a 3-tuple of Network objects which contain the mean, upper_bound, and lower_bound for the given Network attribute. Used to save and plot uncertainty information data. Note that providing 's' and 's_mag' as attributes will provide different results. For those who want to directly find uncertainty on dB performance, use 's_mag'. Parameters ---------- attribute : str Attribute to operate on. n_deviations : int, optional Number of standard deviation. The default is 3. Returns ------- ntwk_mean : :class: `~skrf.network.Network` Network of the averaged attribute lower_bound : :class: `~skrf.network.Network` Network of the lower bound of N*sigma deviation. upper_bound : :class: `~skrf.network.Network` Network of the upper bound of N*sigma deviation. Example ------- >>> (ntwk_mean, ntwk_lb, ntwk_ub) = my_ntwk_set.uncertainty_ntwk_triplet('s') >>> (ntwk_mean, ntwk_lb, ntwk_ub) = my_ntwk_set.uncertainty_ntwk_triplet('s_mag') """ ntwk_mean = getattr(self, 'mean_'+attribute) ntwk_std = getattr(self, 'std_'+attribute) ntwk_std.s = n_deviations * ntwk_std.s upper_bound = (ntwk_mean + ntwk_std) lower_bound = (ntwk_mean - ntwk_std) return (ntwk_mean, lower_bound, upper_bound) def datetime_index(self) -> list: """ Create a datetime index from networks names. this is just: `[rf.now_string_2_dt(k.name ) for k in self]` """ return [now_string_2_dt(k.name ) for k in self] # io def write(self, file=None, *args, **kwargs): r""" Write the NetworkSet to disk using :func:`~skrf.io.general.write` Parameters ---------- file : str or file-object filename or a file-object. If left as None then the filename will be set to Calibration.name, if its not None. If both are None, ValueError is raised. \*args, \*\*kwargs : arguments and keyword arguments passed through to :func:`~skrf.io.general.write` Notes ----- If the self.name is not None and file is can left as None and the resultant file will have the `.ns` extension appended to the filename. Examples --------- >>> ns.name = 'my_ns' >>> ns.write() See Also --------- skrf.io.general.write skrf.io.general.read """ # this import is delayed until here because of a circular dependency from .io.general import write if file is None: if self.name is None: raise (ValueError('No filename given. You must provide a filename, or set the name attribute')) file = self.name write(file, self, *args, **kwargs) def write_spreadsheet(self, *args, **kwargs): """ Write contents of network to a spreadsheet, for your boss to use. Example ------- >>> ns.write_spreadsheet() # the ns.name attribute must exist >>> ns.write_spreadsheet(file_name='testing.xlsx') See Also --------- skrf.io.general.network_2_spreadsheet """ from .io.general import networkset_2_spreadsheet networkset_2_spreadsheet(self, *args, **kwargs) def write_mdif(self, filename: str, values: dict | None = None, data_types: dict | None = None, comments: list[str] | None = None, **kwargs): """Convert a scikit-rf NetworkSet object to a Generalized MDIF file. Parameters ---------- filename : string Output MDIF file name. values : dictionary or None. Default is None. The keys of the dictionary are MDIF variables and its values are a list of the parameter values. If None, then the values will be set to the NetworkSet names and the datatypes will be set to "string". data_types: dictionary or None. Default is None. The keys are MDIF variables and the value are datatypes specified by the following strings: "int", "double", and "string" comments: list of strings Comments to add to output_file. Each list items is a separate comment line **kwargs: dictionary with extra arguments to pass through to the underlying Mdif.write and Network.write_touchstone methods See Also -------- from_mdif : Create a NetworkSet from a MDIF file. params_values : parameters values params_types : parameters types """ from .io import Mdif if comments is None: comments = [] Mdif.write(ns=self, filename=filename, values=values, data_types=data_types, comments=comments, **kwargs) def ntwk_attr_2_df(self, attr='s_db', m=0, n=0, *args, **kwargs): """ Converts an attributes of the Networks within a NetworkSet to a Pandas DataFrame. Examples -------- >>> df = ns.ntwk_attr_2_df('s_db', m=1, n=0) >>> df.to_excel('output.xls') # see Pandas docs for more info """ from pandas import DataFrame, Index, Series index = Index( self[0].frequency.f_scaled, name=f'Freq({self[0].frequency.unit})' ) df = DataFrame( {f'{k.name}': Series(getattr(k, attr)[:,m,n],index=index) for k in self}, index = index, ) return df def interpolate_from_network(self, ntw_param: ArrayLike, x: float, interp_kind: str = 'linear'): """ Interpolate a Network from a NetworkSet, as a multi-file N-port network. Assumes that the NetworkSet contains N-port networks with same number of ports N and same number of frequency points. These networks differ from an given array parameter `interp_param`, which is used to interpolate the returned Network. Length of `interp_param` should be equal to the length of the NetworkSet. Parameters ---------- ntw_param : (N,) array_like A 1-D array of real values. The length of ntw_param must be equal to the length of the NetworkSet x : real Point to evaluate the interpolated network at interp_kind: str Specifies the kind of interpolation as a string: 'linear', 'nearest', 'zero', 'slinear', 'quadratic', 'cubic'. See :class:`scipy.interpolate.interp1d` for detailed description. Default is 'linear'. Returns ------- ntw : class:`~skrf.network.Network` Network interpolated at x Example ------- Assuming that `ns` is a NetworkSet containing 3 Networks (length=3) : >>> param_x = [1, 2, 3] # a parameter associated to each Network >>> x0 = 1.5 # parameter value to interpolate for >>> interp_ntwk = ns.interpolate_from_network(param_x, x0) """ ntw = self[0].copy() # Interpolating the scattering parameters s = np.array([self[idx].s for idx in range(len(self))]) f = interp1d(ntw_param, s, axis=0, kind=interp_kind) ntw.s = f(x) return ntw def interpolate_frequency(self, freq_or_n: Frequency | NumberLike, basis: str = 's', coords: str = 'cart', f_kwargs: dict = None, **kwargs) -> NetworkSet: """Interpolates each network in the set by frequency by calling :meth:`Network.interpolate`. Parameters ---------- freq_or_n : :class:`~skrf.frequency.Frequency` or int or list-like The new frequency over which to interpolate. this arg may be one of the following: * a new :class:`~skrf.frequency.Frequency` object * an int: the current frequency span is resampled linearly. * a list-like: create a new frequency using :meth:`~skrf.frequency.Frequency.from_f` basis : ['s','z','y','a'], etc The network parameter to interpolate coords : string Coordinate system to use for interpolation: 'cart' or 'polar': 'cart' is cartesian is Re/Im. 'polar' is unwrapped phase/mag f_kwargs : dict Key word arguments that are passed to the new :class:`Frequency` object **kwargs : keyword arguments passed to :func:`scipy.interpolate.interp1d` initializer. `kind` controls interpolation type. `kind` = `rational` uses interpolation by rational polynomials. `d` kwarg controls the degree of rational polynomials when `kind`=`rational`. Defaults to 4. Returns ------- NetworkSet : :class:`NetworkSet` New NetworkSet with interpolated frequencies """ return NetworkSet([ntwk.interpolate(freq_or_n, basis, coords, f_kwargs, **kwargs) for ntwk in self.ntwk_set]) def has_params(self) -> bool: """ Check is all Networks in the NetworkSet have a similar params dictionary. Returns ------- bool True is all Networks have a .params dictionary (of same size), False otherwise """ # does all networks have a params property? if not all(hasattr(ntwk, 'params') for ntwk in self.ntwk_set): return False # are all params property been set? if any(ntwk.params is None for ntwk in self.ntwk_set): return False # are they all of the same size? params_len = len(self.ntwk_set[0].params) if not all(len(ntwk.params) == params_len for ntwk in self.ntwk_set): return False # are all the dict keys the same? params_keys = self.ntwk_set[0].params.keys() if not all(ntwk.params.keys() == params_keys for ntwk in self.ntwk_set): return False # then we are all good return True @property def params(self) -> list: """ Return the list of parameter names stored in the Network of the NetworkSet. Similar to the `dims` property, except it returns a list instead of a view. Returns ------- list: list list of the parameter names if any. Empty list if no parameter found. """ return list(self.dims) @property def params_values(self) -> dict | None: """ Return a dictionary containing all parameters and their values. Returns ------- values : dict or None. Dictionary of all parameters names and their values (into a list). Return None if no parameters are defined in the NetworkSet. """ if self.has_params(): # creating a dict of empty lists for each of the param keys values = {key: [] for key in self.dims} for ntwk in self.ntwk_set: for key, value in ntwk.params.items(): values[key].append(value) return values else: return None @property def params_types(self) -> dict | None: """ Return a dictionary describing the data type of each parameters. Returns ------- data_types : dict or None. Dictionary of the (guessed) type of each parameters. Return None if no parameters are defined in the NetworkSet. """ # for each parameter, scan all the value and try to guess the type # If is not a int, and not a float (double), then it's a string if self.has_params(): data_types = {} values = self.params_values for key in values: try: _ = [int(v) for v in values[key]] data_types[key] = 'int' except ValueError: # not an int try: _ = [float(v) for v in values[key]] data_types[key] = 'double' except ValueError: # not a float -> then a string data_types[key] = 'string' return data_types else: return None def to_dataframe(self, attrs: list[str] = None, ports: list[tuple[int, int]] = None, port_sep: str | None = None): """ Convert attributes of a NetworkSet to a pandas DataFrame. Use the same parameters than :func:`skrf.io.general.network_2_dataframe` Parameters ---------- attrs : list of string Network attributes to convert, like ['s_db','s_deg'] ports : list of tuples list of port pairs to write. defaults to ntwk.port_tuples (like [[0,0]]) port_sep : string defaults to None, which means a empty string "" is used for networks with lower than 10 ports. (s_db 11, s_db 21) For more than ten ports a "_" is used to avoid ambiguity. (s_db 1_1, s_db 2_1) For consistent behaviour it's recommended to specify "_" or "," explicitly. Returns ------- df : `pandas.DataFrame` Raises ------ ValueError : if the networkset doesn't have parameters See Also --------- skrf.io.general.network_2_dataframe """ if not self.params: raise ValueError( "The NetworkSet must have parameters to be combined into a dataframe. " "Try using `ntwk_attr_2_df` instead." ) dfs = [] for ntwk in self.ntwk_set: # Create a dataframe for each network df = ntwk.to_dataframe(attrs=attrs, ports=ports, port_sep=port_sep) # Insert the parameters and values for each network df[list(ntwk.params.keys())] = list(ntwk.params.values()) # Get the columns by type data_cols = df.columns[:-1 * len(ntwk.params)].tolist() param_cols = df.columns[-1 * len(ntwk.params):].tolist() # Append to the list of dataframes with the parameter columns first dfs.append(df[param_cols + data_cols]) # Return a concatenated dataframe return pd.concat(dfs) def sel(self, indexers: Mapping[Any, Any] = None) -> NetworkSet: """ Select Network(s) in the NetworkSet from a given value of a parameter. Parameters ---------- indexers : dict, optional A dict with keys matching dimensions and values given by scalars, or arrays of parameters. Default is None, which returns the entire NetworkSet Returns ------- ns : NetworkSet NetworkSet containing the selected Networks or an empty NetworkSet if no match is found Example ------- Creating a dummy example: >>> params = [ {'a':0, 'X':10, 'c':'A'}, {'a':1, 'X':10, 'c':'A'}, {'a':2, 'X':10, 'c':'A'}, {'a':1, 'X':20, 'c':'A'}, {'a':0, 'X':20, 'c':'A'}, ] >>> freq1 = rf.Frequency(75, 110, 101, 'ghz') >>> ntwks_params = [rf.Network(frequency=freq1, s=np.random.rand(len(freq1),2,2), name=f'ntwk_{m}', comment=f'ntwk_{m}', params=params) \ for (m, params) in enumerate(params) ] >>> ns = rf.NetworkSet(ntwks_params) Selecting the sub-NetworkSet matching scalar parameters: >>> ns.sel({'a': 1}) # len == 2 >>> ns.sel({'a': 0, 'X': 10}) # len == 1 Selectong the sub-NetworkSet matching a range of parameters: >>> ns.sel({'a': 0, 'X': [10,20]}) # len == 2 >>> ns.sel({'a': [0,1], 'X': [10,20]}) # len == 4 If using a parameter name of value that does not exist, returns empty NetworkSet: >>> ns.sel({'a': -1}) # len == 0 >>> ns.sel({'duh': 0}) # len == 0 """ from collections.abc import Iterable if not indexers: # None or {} return self.copy() if not self.has_params(): return NetworkSet() if not isinstance(indexers, dict): raise TypeError('indexers should be a dictionary.') for p in indexers.keys(): if p not in self.dims: return NetworkSet() ntwk_list = [] for k in self.ntwk_set: match_list = [k.params[p] in (v if isinstance(v, Iterable) else [v]) for (p, v) in indexers.items()] if all(match_list): ntwk_list.append(k) if ntwk_list: return NetworkSet(ntwk_list) else: # no match found return NetworkSet() def interpolate_from_params(self, param: str, x: float, sub_params: dict=None, interp_kind: str = 'linear'): """ Interpolate a Network from given parameters of NetworkSet's Networks. Parameters ---------- param : string Name of the parameter to interpolate the NetworkSet with x : float Point to evaluate the interpolated network at sub_params : dict, optional Dictionary of parameter/values to filter the NetworkSet, if necessary to avoid an ambiguity. Default is empty dict. interp_kind: str Specifies the kind of interpolation as a string: 'linear', 'nearest', 'zero', 'slinear', 'quadratic', 'cubic'. Cf :class:`scipy.interpolate.interp1d` for detailed description. Default is 'linear'. Returns ------- ntw : class:`~skrf.network.Network` Network interpolated at x Raises ------ ValueError : if the interpolating param/value are incorrect or ambiguous Example ------- Creating a dummy example: >>> params = [ {'a':0, 'X':10, 'c':'A'}, {'a':1, 'X':10, 'c':'A'}, {'a':2, 'X':10, 'c':'A'}, {'a':1, 'X':20, 'c':'A'}, {'a':0, 'X':20, 'c':'A'}, ] >>> freq1 = rf.Frequency(75, 110, 101, 'ghz') >>> ntwks_params = [rf.Network(frequency=freq1, s=np.random.rand(len(freq1),2,2), name=f'ntwk_{m}', comment=f'ntwk_{m}', params=params) \ for (m, params) in enumerate(params) ] >>> ns = rf.NetworkSet(ntwks_params) Interpolated Network for a=1.2 within X=10 Networks: >>> ns.interpolate_from_params('a', 1.2, {'X': 10}) """ # checking interpolating param and values if sub_params is None: sub_params = {} if param not in self.params: raise ValueError(f'Parameter {param} is not found in the NetworkSet params.') if isinstance(x, Number): if not (min(self.coords[param]) < x < max(self.coords[param])): raise ValueError(f'Out of bound values: {x} is not inside {self.coords[param]}. Cannot interpolate.') else: raise ValueError('Cannot interpolate between string-based parameters.') # checking sub-parameters if sub_params: for (p, v) in sub_params.items(): # of course it should exist if p not in self.dims: raise ValueError(f'Parameter {p} is not found in the NetworkSet params.') # check if each sub-param exist in the parameters if v not in self.coords[p]: # also deals with string case raise ValueError(f'Parameter {p} value {v} is not found in the NetworkSet params.') # interpolating the sub-NetworkSet matching the passed sub-parameters sub_ns = self.sel(sub_params) interp_ntwk = sub_ns.interpolate_from_network(sub_ns.coords[param], x, interp_kind) return interp_ntwk @copy_doc(skrf_plt.animate) def animate(self, *args, **kwargs): skrf_plt.animate(self, *args, **kwargs) @copy_doc(skrf_plt.plot_uncertainty_bounds_component) def plot_uncertainty_bounds_component(self, *args, **kwargs): skrf_plt.plot_uncertainty_bounds_component(self, *args, **kwargs) @copy_doc(skrf_plt.plot_minmax_bounds_component) def plot_minmax_bounds_component(self, *args, **kwargs): skrf_plt.plot_minmax_bounds_component(self, *args, **kwargs) @copy_doc(skrf_plt.plot_uncertainty_bounds_s_db) def plot_uncertainty_bounds_s_db(self, *args, **kwargs): skrf_plt.plot_uncertainty_bounds_s_db(self, *args, **kwargs) @copy_doc(skrf_plt.plot_minmax_bounds_s_db) def plot_minmax_bounds_s_db(self, *args, **kwargs): skrf_plt.plot_minmax_bounds_s_db(self, *args, **kwargs) @copy_doc(skrf_plt.plot_minmax_bounds_s_db10) def plot_minmax_bounds_s_db10(self, *args, **kwargs): skrf_plt.plot_minmax_bounds_s_db10(self, *args, **kwargs) @copy_doc(skrf_plt.plot_uncertainty_bounds_s_time_db) def plot_uncertainty_bounds_s_time_db(self, *args, **kwargs): skrf_plt.plot_uncertainty_bounds_s_time_db(self, *args, **kwargs) @copy_doc(skrf_plt.plot_minmax_bounds_s_time_db) def plot_minmax_bounds_s_time_db(self, *args, **kwargs): skrf_plt.plot_minmax_bounds_s_time_db(self, *args, **kwargs) @copy_doc(skrf_plt.plot_uncertainty_decomposition) def plot_uncertainty_decomposition(self, *args, **kwargs): skrf_plt.plot_uncertainty_decomposition(self, *args, **kwargs) @copy_doc(skrf_plt.plot_logsigma) def plot_logsigma(self, *args, **kwargs): skrf_plt.plot_logsigma(self, *args, **kwargs) @copy_doc(skrf_plt.signature) def signature(self, *args, **kwargs): skrf_plt.signature(self, *args, **kwargs) @copy_doc(skrf_plt.plot_violin) def plot_violin(self, attribute, *args, **kwargs): if "time" not in attribute: skrf_plt.plot_violin(self, attribute, *args,**kwargs) else: raise NotImplementedError("Violin plots are not implemented for time based parameters") def func_on_networks(ntwk_list, func, attribute='s',name=None, *args,\ **kwargs): r""" Applies a function to some attribute of a list of networks. Returns the result in the form of a Network. This means information that may not be s-parameters is stored in the s-matrix of the returned Network. Parameters ------------- ntwk_list : list of :class:`~skrf.network.Network` objects list of Networks on which to apply `func` to func : function function to operate on `ntwk_list` s-matrices attribute : string attribute of Network's in ntwk_list for func to act on \*args,\*\*kwargs : arguments and keyword arguments passed to func Returns --------- ntwk : :class:`~skrf.network.Network` Network with s-matrix the result of func, operating on ntwk_list's s-matrices Examples ---------- averaging can be implemented with func_on_networks by >>> func_on_networks(ntwk_list, mean) """ data_matrix = np.array([getattr(ntwk, attribute) for ntwk in ntwk_list]) new_ntwk = ntwk_list[0].copy() new_ntwk.s = func(data_matrix,axis=0,**kwargs) if name is not None: new_ntwk.name = name return new_ntwk # short hand name for convenience fon = func_on_networks def getset(ntwk_dict, s, *args, **kwargs): r""" Creates a :class:`NetworkSet`, of all :class:`~skrf.network.Network`s objects in a dictionary that contain `s` in its key. This is useful for dealing with the output of :func:`~skrf.io.general.load_all_touchstones`, which contains Networks grouped by some kind of naming convention. Parameters ------------ ntwk_dict : dictionary of Network objects network dictionary that contains a set of keys `s` s : string string contained in the keys of ntwk_dict that are to be in the NetworkSet that is returned \*args,\*\*kwargs : passed to NetworkSet() Returns -------- ntwk_set : NetworkSet object A NetworkSet that made from values of ntwk_dict with `s` in their key Examples --------- >>>ntwk_dict = rf.load_all_touchstone('my_dir') >>>set5v = getset(ntwk_dict,'5v') >>>set10v = getset(ntwk_dict,'10v') """ ntwk_list = [ntwk_dict[k] for k in ntwk_dict if s in k] if len(ntwk_list) > 0: return NetworkSet( ntwk_list,*args, **kwargs) else: print(f'Warning: No keys in ntwk_dict contain \'{s}\'') return None def tuner_constellation(name='tuner', singlefreq=76, Z0=50, r_lin = 9, phi_lin=21, TNWformat=True): r = np.linspace(0.1,0.9,r_lin) a = np.linspace(0,2*np.pi,phi_lin) r_, a_ = np.meshgrid(r,a) c_ = r_ *np.exp(1j * a_) g= c_.flatten() x = np.real(g) y = np.imag(g) if TNWformat : TNL = dict() # for ii, gi in enumerate(g) : for ii, gi in enumerate(g) : TNL['pos'+str(ii)] = Network(f = [singlefreq ], s=[[[gi]]], z0=[[Z0]], name=name +'_' + str(ii)) TNW = NetworkSet(TNL, name=name) return TNW, x,y,g else : return x,y,g