Functions

Welcome to the Functions page! Here, we will delve into the details of each function, its purpose, parameters and returns. Links to the description of returned objects on the Classes and Objects page will be provided.

Note

Currently, not all functions that are included in PT3S are documented. These will be added in the future.

Read SIR 3S Model and Results

dxAndMxHelperFcts.readDxAndMx(dbFile, preventPklDump=False, forceSir3sRead=False, maxRecords=None, mxsVecsResults2MxDf=None, mxsVecsResults2MxDfVecAggs=None, crs=None, logPathOutputFct=<function relpath>, SirCalcExePath=None)[source]

Reads SIR 3S model and SIR 3S results and returns a dxWithMx object - also called m object.

Use maxRecords=0 to read only the model. Use maxRecords=1 to read only STAT (the steady state result). Use maxRecords=-1 to (re-)calculate the model by SirCalc.

Parameters:

dbFile (str) – Path to SIR 3S’ database file (‘modell.db3’ or ‘modell.mdb’). The database is read into a Dx object. The corresponding results are read into an Mx object if available.
preventPklDump (bool, optional, default=False) – Determines whether to prevent dumping objects read to pickle. If True, existing pickles are deleted, SIR 3S’ sources are read and no pickles are written. If False 3 pickles are written or overwritten if older than SIR 3S’ sources.
forceSir3sRead (bool, optional, default=False) – Determines whether to force reading from SIR 3S’ sources even if newer pickles exists. By default pickles are read if newer than SIR 3S’ sources.
maxRecords (int, optional, default=None) – Use maxRecords=0 to read only the model. Use maxRecords=1 to read only STAT (the steady state result). Maximum number of MX-Results to read. If None, all results are read. Use maxRecords=-1 to (re-)calculate the model by SirCalc (by the newest SirCalc available below C:\3S).
mxsVecsResults2MxDf (list, optional, default=None) – List of regular expressions for SIR 3S’ Vector-Results to be included in mx.df. Note that integrating Vector-Results in mx.df can significantly increase memory usage. Example 1: ['ROHR~\*~\*~\*~PHR', 'ROHR~\*~\*~\*~FS', 'ROHR~\*~\*~\*~DSI', 'ROHR~\*~\*~\*~DSK'] Example 2: ['KNOT~\*~\*~\*~VOLD','ROHR~\*~\*~\*~VOLDA']
mxsVecsResults2MxDfVecAggs (list, optional, default=None) – List of timesteps indices for SIR 3S’ Vector-Results to be included in mx.dfVecAggs. Note that integrating all timesteps in mx.dfVecAggs will increase memory usage up to MXS-Size. Example: [3, 42, 666, -1] (-1: last timestep). 3: 3rd timestep. 42: 42th timestep. 666: 666th timestep.
crs (str, optional, default=None) – (=coordinate reference system) Determines crs used in geopandas-Dfs (Possible value:’EPSG:25832’). If None, crs will be read from SIR 3S’ database file.
logPathOutputFct (func, optional, default=os.path.relpath) – func logPathOutputFct(fileName) is used for logoutput of filenames unless explicitly stated otherwise in the logoutput
SirCalcExePath (str, optional, default=None) – SirCalcExePath can be used to specify the path to the SirCalc.exe that is used for calculations if maxRecords<0

Returns:

An object containing the SIR 3S model and SIR 3S results - also called m object.

Return type:

dxWithMx

Returns m Object.

Usage Tutorial

Enter the name of the .db3 file you want to read

>>> dbFilename="Example1"

Enter the path to the dir, where this .db3 file is located. In this case the Example data included in PT3S is used.

>>> rootdir=os.path.join(os.path.dirname(os.path.abspath(dxAndMxHelperFcts.__file__)), 'Examples')

Concatenate the rootdir with the dbFilename

>>> dbFile=os.path.join(rootdir, dbFilename + '.db3')

dbFile can now be used as a parameter for readDxAndMx()

>>> dbFile
'C:\\Users\\jablonski\\3S\\PT3S\\Examples\\Example1.db3'

Create a dxWithMx object using readDxAndMx().

>>> m=dxAndMxHelperFcts.readDxAndMx(dbFile=dbFile)

Refer to the Examples page. The Examples 1-X use this function.

Read SIR 3S Results only

dxAndMxHelperFcts.readMx(wDirMx, logPathOutputFct=<function relpath>)[source]

Reads SIR 3S results and returns a Mx object.

Parameters:

wDirMx (str) – Path to Mx-Directory. The results are read into a Mx object via the Mx files.
logPathOutputFct (func, optional, default=os.path.relpath) – func logPathOutputFct(fileName) is used for logoutput of filenames unless explicitly stated otherwise in the logoutput. Defaults to os.path.relpath.

Returns:

Mx object with two attributes: - mx.df: pandas-Df (‘time curve data’) from from SIR 3S’ MXS file(s) - mx.dfVecAggs: pandas-Df (‘vector data’) from SIR 3S’ MXS file(s)

Return type:

Mx object

Returns Mx object.

Refer to Example 2: Time Curves. It uses this function.

Methods

Methods regarding m Object 

switchV3DfColsToMultiindex

dxAndMxHelperFcts.dxWithMx.switchV3DfColsToMultiindex(self): Switches V3-Df cols to Multiindex-Cols. switchV3DfColsToMultiindex(): switch cols in V3_ROHR, V3_FWVB, V3_KNOT, V3_VBEL to Multiindex

Methods regarding Dx object 

update

Dx.Dx.update(self, dfUpd, updInverseValue=None)

Updates dbFile (SQLite only)

Parameters:

dfUpd (df) – df with update data
updInverseValue (?, optional, default=None) – value to use for attribValue for inverse objects

Returns:

rowsAffectedTotal

Note

Comprehensive changes to model data should be made via the SIR 3S user interface. Or via the SIR 3S import interfaces which - depending on type/operation/parameterization - can also overwrite (update) existing model data. Nonetheless, scripted model changes can be helpful.

dfUpd’s cols used:

table i.e. ‘FWVB’
attrib i.e. ‘W0’

dfUpd’s cols optional:

attribValue, default=dfUpd[attrib]
xk, default=’tk’
xkValue, default=dfUpd[xk]

row-wise:

set attrib to attribValue in table where xk is xkValue
update an attribute of an object

updInverseValue:

set attrib to updInverseValue for all objects of type table not mentioned in dfUpd

insert

Dx.Dx.insert(self, table, dfIns, xkFct=<function fXk>)

Inserts into a dbFile’s table (SQLite only)

Parameters:

table (str) – table to insert to
dfIns (df) – df with insert data
xkFct (func, optional, default=Dx.fXk) – func to call row-wise to obtain (pk, rk, tk) for an record to insert

Returns:

rowsAffected, dfIns (a copy of dfIns; cols pk, rk, tk: inserted values; cols pkOrig, rkOrig, tkOrig: original values)

Note

New model mass data should be created via the SIR 3S import interfaces. Nevertheless, generating model mass data via script can be helpful.

dfIns’ cols used:

all cols which are also cols of table

row-wise:

insert into table

importFromSIR3S

Dx.Dx.importFromSIR3S(self, dbSrc, tablesToImport=['STRASSE', 'LTGR', 'DTRO', 'DTRO_ROWD', 'KNOT', 'KNOT_BZ', 'ROHR', 'ROHR_BZ', 'FWVB', 'FWVB_BZ', 'LAYR'], fksNotToFillWithDstTemplateValues=['fkKI', 'fkKK', 'fkDTRO_ROWD', 'fkLTGR', 'fkSTRASSE'], fctsToCall={'*': <function fimportFromSIR3S>}, fctsToCallLogging=True)

Import data from an other SIR 3S Model (SQLite only)

Parameters:

dbSrc (str) – SIR 3S dbFile to import from
tablesToImport (list of tabNames, optional, default=['STRASSE','LTGR','DTRO','DTRO_ROWD' ,'KNOT','KNOT_BZ','ROHR','ROHR_BZ','FWVB','FWVB_BZ' ,'LAYR']) – tabNames to import from
fksNotToFillWithDstTemplateValues (list of fk starting colNames, optional, default=['fkKI','fkKK','fkDTRO_ROWD','fkLTGR','fkSTRASSE']) – colNames starting with fk not to set to the corresponding Dst-Template-Value
fctsToCall (dct of functions, optional, default={'*':fimportFromSIR3S}; f('*') is called if defined and then the object-specific f(OBJ) is called if defined) – dct of functions to call before import
fctsToCallLogging (bool, optional, default=True) – decide if fctsToCall shall generate Log-Output

Note

Model data from annother SIR 3S Model should be imported via the SIR 3S export/import interfaces. I.e. export in Src Sdf/Csv, import in Dst the exported Sdf/Csv. Or copy in Src and paste in Dst. Or export/import SIR 3S Blocks. Nevertheless, importing from another Model via script can be helpful.

Note

Template-Objects are Objects with col ‘KENNUNG’ < 0. Template-Objects are not copied from Src to Dst. For objects with Templates defined all Non-Null fk-Starting Template-Attributes from Dst are set except for: fksNotToFillWithDstTemplateValues. It follows that i.e. for KNOT(_BZ), ROHR(_BZ), FWVB(_BZ) fkDE is set to the corresponding fkDE Dst-Template-Attribute if defined. For all objects fkDE is finally set to fkBASIS(fkBZ) of the SYSTEMKONFIG(3)-Model if SYSTEMKONFIG(3) is defined.

Note

Dst and Src: SIR 3S Version and CRS (coordinate reference system) should be identical, QGIS-Export should be done (to ensure correct and matching GEOMWKBs in Dst and Src).

setLayerContentTo

Dx.Dx.setLayerContentTo(self, layerName, df)

Updates content of layerName to df’s-content

Parameters:: layerName (str) – name of an existing layer
Returns:: rowsAffected

Note

Groups or layers are used in SIR 3S as a feature for data access, data filtering and grouping. The assignment of objects to groups should be done (explicit) via the SIR 3S user interface or (implicit) via the SIR 3S import interfaces. Nonetheless, scripted assignment can be useful.

df’s cols used:

TYPE
ID

SdfCsv

sdfCsv.SdfCsv.__init__(self, csvFile='aSdfCsvFile.csv', encoding='cp1252')

Parameters:

csvFile (str) – a SDF-CSV-File
encoding (str) – encoding

Note

SIR 3S imports SDF-CSV-Files. However sometimes it is convenient to have a look at the original SDF-CSV-File content with Python. I.e. to explore the original hierarchical layer structure in comparison to the flat layer structure in the SIR 3S model. Or i.e. to check against the SIR 3S SDF-CSV-File import- and export-function result. In general, one can say that the SDF-CSV format for pipe network data (for pipe network models) is so widespread in Germany that it makes sense to have an SIR 3S affine function which maps the SDF-CSV-File to pandas dfs.

The returned object has the following structure:

dataFrames: dct with dfs

dataFrames[‘FEL’]: a df with the definition of the columns of all types; i.e. ‘KNO’ is a type

dataFrames[‘KNO’]: a df with data for objects of type ‘KNO’

dataFramesDesc: dct with descs; i.e. dataFramesDesc[‘KNO’]: ‘Knotendaten’

The returned object has the following functions:

getHierarchicalLayernames: returns: {originalLayername:hierarchicalLayername, …}

Plot Network Color Diagram

ncd.pNcd_pipes(ax=None, gdf=None, attribute=None, colors=['darkgreen', 'magenta'], legend_fmt=None, legend_values=None, norm_min=None, norm_max=None, query=None, line_width_factor=10, zorder=None)[source]

pNcd_pipes: Plots pipes on axis with customization options.

Parameters:

ax (matplotlib.axes.Axes, optional) – Matplotlib axis object. If None, a new axis is created.
gdf (geopandas.GeoDataFrame) – Geospatial DataFrame containing the data to plot.
attribute (str) – Column name in gdf of the data that should be plotted.
colors (list, optional) – List of colors to use for the colormap. Default is [‘darkgreen’, ‘magenta’].
legend_fmt (str, optional) – Legend text for attribute. Default is attribute + ‘{:.4f}’.
legend_values (list, optional) – Specific values to use for value steps in legend. Default is None.
norm_min (float, optional) – Minimum value for normalization. Default is None.
norm_max (float, optional) – Maximum value for normalization. Default is None.
query (str, optional) – Query string to filter the data. Default is None.
line_width_factor (float, optional) – Factor to influence width of the lines in the plot. Default is 10.
zorder (float, optional) – Determines order of plotting when calling the function multilpe times. Default is None.

Returns:

patches.

Return type:

matplotlib.patches.Patch

ncd.pNcd_nodes(ax=None, gdf=None, attribute=None, colors=['darkgreen', 'magenta'], legend_fmt=None, legend_values=None, norm_min=None, norm_max=None, query=None, marker_style='o', marker_size_factor=1000.0, zorder=None)[source]

pNcd_nodes: Plots nodes on axis with customization options.

Parameters:

ax (matplotlib.axes.Axes, optional) – Matplotlib axis object. If None, a new axis is created.
gdf (geopandas.GeoDataFrame) – Geospatial DataFrame containing the data to plot.
attribute (str) – Column name in gdf of the data that should be plotted.
colors (list, optional) – List of colors to use for the colormap. Default is [‘darkgreen’, ‘magenta’].
legend_fmt (str, optional) – Legend text for attribute. Default is attribute + ‘{:.4f}’.
legend_values (list, optional) – Specific values to use for value steps in legend. Default is None.
norm_min (float, optional) – Minimum value for normalization. Default is None.
norm_max (float, optional) – Maximum value for normalization. Default is None.
query (str, optional) – Query string to filter the data. Default is None.
marker_style (str, optional) – Style of the markers in the plot. Default is ‘o’.
marker_size_factor (float, optional) – Factor to influence size of the markers in the plot. Default is 1000.0.
zorder (float, optional) – Determines order of plotting when calling the function multilpe times. Default is None.

Returns:

patches.

Return type:

matplotlib.patches.Patch

Usage Tutorial

Plot on an axes. Use pNcd_pipes for pipes and pNcd_nodes for nodes.

If you plot multiple times on the same axes, use zorder to determine plotting order.

Refer to Example 1: Interactive Map and Network Color Diagram. It uses this function.

>>> fig, ax = plt.subplots()
>>> pipes_patches = ncd.pNcd_pipes(ax=ax, gdf=gdf_ROHR, attribute='DI', zorder=1)
>>> nodes_patches = ncd.pNcd_nodes(ax=ax, gdf=gdf_FWVB, attribute='QM', zorder=2)
>>> all_patches = pipes_patches + nodes_patches
>>> ax.legend(handles=all_patches, loc='best') 
>>> plt.show()
Figure(640x480)

Plot Source Spectrum

ncd.plot_src_spectrum(ax=None, gdf=None, attribute=None, colors=None, line_width=2)[source]

Plots the source spectrum based on the provided GeoDataFrame and attributes.

Parameters:

ax (matplotlib.axes.Axes, optional) – The axis to plot on. If None, a new axis is created.
gdf (geopandas.GeoDataFrame) – The GeoDataFrame containing the data to plot.
attribute (str) – The attribute column in the GeoDataFrame to use for color mixing.
colors (list of np.ndarray) – The colors to use for mixing.
line_width (int, optional, default=2) – The width of the lines in the plot.

Refer to Example 7: Source Spectrum. It uses this function.

Functions

Read SIR 3S Model and Results

Usage Tutorial

Read SIR 3S Results only

Methods

Methods regarding m Object

switchV3DfColsToMultiindex

Methods regarding Dx object

update

insert

importFromSIR3S

setLayerContentTo

SdfCsv

Plot Network Color Diagram

Usage Tutorial

Plot Source Spectrum

Methods regarding m Object 

Methods regarding Dx object 