Network Connections Plotting API

bmtool.bmplot.connections.is_notebook()

Detect if code is running in a Jupyter notebook environment.

Returns:

Type	Description
bool	True if running in a Jupyter notebook, False otherwise.

Notes

This is used to determine whether to call plt.show() explicitly or rely on Jupyter's automatic display functionality.

Examples:

>>> if is_notebook():
...     plt.show()

Source code in bmtool/bmplot/connections.py

def is_notebook() -> bool:
    """
    Detect if code is running in a Jupyter notebook environment.

    Returns
    -------
    bool
        True if running in a Jupyter notebook, False otherwise.

    Notes
    -----
    This is used to determine whether to call plt.show() explicitly or
    rely on Jupyter's automatic display functionality.

    Examples
    --------
    >>> if is_notebook():
    ...     plt.show()
    """
    try:
        shell = get_ipython().__class__.__name__
        if shell == "ZMQInteractiveShell":
            return True  # Jupyter notebook or qtconsole
        elif shell == "TerminalInteractiveShell":
            return False  # Terminal running IPython
        else:
            return False  # Other type (?)
    except NameError:
        return False  # Probably standard Python interpreter

bmtool.bmplot.connections.total_connection_matrix(config, title=None, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=False, synaptic_info='0', include_gap=True)

Generate a plot displaying total connections or other synaptic statistics.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
title	str	Title for the plot. If None, a default title will be used.	None
sources	str	Comma-separated string of network names to use as sources.	None
targets	str	Comma-separated string of network names to use as targets.	None
sids	str	Comma-separated string of source node identifiers to filter.	None
tids	str	Comma-separated string of target node identifiers to filter.	None
no_prepend_pop	bool	If True, don't display population name before sid or tid in the plot. Default is False.	False
synaptic_info	str	Type of information to display. Options: - '0': Total connections (default) - '1': Mean and standard deviation of connections - '2': All synapse .mod files used - '3': All synapse .json files used	'0'
include_gap	bool	If True, include gap junctions and chemical synapses in the analysis. If False, only include chemical synapses. Default is True.	True

Returns:

Type	Description
tuple of (Figure, Axes)	The matplotlib Figure and Axes objects for further customization or saving.

Raises:

Type	Description
Exception	If config is not defined or sources/targets are not defined.

Examples:

>>> total_connection_matrix(
...     config='config.json',
...     sources='PN',
...     targets='LN',
...     title='PN to LN Connections'
... )

Source code in bmtool/bmplot/connections.py

def total_connection_matrix(
    config: str,
    title: Optional[str] = None,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: bool = False,
    synaptic_info: str = "0",
    include_gap: bool = True,
) -> Tuple[Any, Any]:
    """
    Generate a plot displaying total connections or other synaptic statistics.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    title : str, optional
        Title for the plot. If None, a default title will be used.
    sources : str, optional
        Comma-separated string of network names to use as sources.
    targets : str, optional
        Comma-separated string of network names to use as targets.
    sids : str, optional
        Comma-separated string of source node identifiers to filter.
    tids : str, optional
        Comma-separated string of target node identifiers to filter.
    no_prepend_pop : bool, optional
        If True, don't display population name before sid or tid in the plot. Default is False.
    synaptic_info : str, optional
        Type of information to display. Options:
        - '0': Total connections (default)
        - '1': Mean and standard deviation of connections
        - '2': All synapse .mod files used
        - '3': All synapse .json files used
    include_gap : bool, optional
        If True, include gap junctions and chemical synapses in the analysis.
        If False, only include chemical synapses. Default is True.

    Returns
    -------
    tuple of (Figure, Axes)
        The matplotlib Figure and Axes objects for further customization or saving.

    Raises
    ------
    Exception
        If config is not defined or sources/targets are not defined.

    Examples
    --------
    >>> total_connection_matrix(
    ...     config='config.json',
    ...     sources='PN',
    ...     targets='LN',
    ...     title='PN to LN Connections'
    ... )
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    sources = sources.split(",")
    targets = targets.split(",")
    if sids:
        sids = sids.split(",")
    else:
        sids = []
    if tids:
        tids = tids.split(",")
    else:
        tids = []
    text, num, source_labels, target_labels = util.connection_totals(
        config=config,
        nodes=None,
        edges=None,
        sources=sources,
        targets=targets,
        sids=sids,
        tids=tids,
        prepend_pop=not no_prepend_pop,
        synaptic_info=synaptic_info,
        include_gap=include_gap,
    )

    if title is None or title == "":
        title = "Total Connections"
    if synaptic_info == "1":
        title = "Mean and Stdev # of Conn on Target"
    if synaptic_info == "2":
        title = "All Synapse .mod Files Used"
    if synaptic_info == "3":
        title = "All Synapse .json Files Used"

    return plot_connection_info(
        text, num, source_labels, target_labels, title, syn_info=synaptic_info
    )

bmtool.bmplot.connections.percent_connection_matrix(config, nodes=None, edges=None, title=None, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=False, method='total', include_gap=True, return_dict=False)

Generates a plot showing the percent connectivity of a network.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
nodes	DataFrame	Pre-loaded node data. If None, will be loaded from config.	None
edges	DataFrame	Pre-loaded edge data. If None, will be loaded from config.	None
title	str	Title for the plot. If None, a default title will be used.	None
sources	str	Comma-separated string of network name(s) to plot.	None
targets	str	Comma-separated string of network name(s) to plot.	None
sids	str	Comma-separated string of source node identifier(s) to filter.	None
tids	str	Comma-separated string of target node identifier(s) to filter.	None
no_prepend_pop	bool	If True, population name is not displayed before sid or tid in the plot. Default is False.	False
method	str	Method for calculating percent connectivity. Options: 'total', 'uni', 'bi'. Default is 'total'.	'total'
include_gap	bool	If True, include gap junctions in analysis. If False, only include chemical synapses. Default is True.	True
return_dict	bool	If True, return connection information as a dictionary. Default is False.	False

Returns:

Type	Description
Union[Tuple[Figure, Axes], Dict]	If return_dict=True, returns a dictionary of connection information. Otherwise, returns a tuple of (Figure, Axes) for further customization or saving.

Raises:

Type	Description
Exception	If config is not defined or sources/targets are not defined.

Examples:

>>> result = percent_connection_matrix(
...     config='config.json',
...     sources='PN',
...     targets='LN',
...     return_dict=True
... )

Source code in bmtool/bmplot/connections.py

def percent_connection_matrix(
    config: str,
    nodes: Optional[pd.DataFrame] = None,
    edges: Optional[pd.DataFrame] = None,
    title: Optional[str] = None,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: bool = False,
    method: str = "total",
    include_gap: bool = True,
    return_dict: bool = False,
) -> Union[Tuple[Any, Any], Dict]:
    """
    Generates a plot showing the percent connectivity of a network.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    nodes : pd.DataFrame, optional
        Pre-loaded node data. If None, will be loaded from config.
    edges : pd.DataFrame, optional
        Pre-loaded edge data. If None, will be loaded from config.
    title : str, optional
        Title for the plot. If None, a default title will be used.
    sources : str, optional
        Comma-separated string of network name(s) to plot.
    targets : str, optional
        Comma-separated string of network name(s) to plot.
    sids : str, optional
        Comma-separated string of source node identifier(s) to filter.
    tids : str, optional
        Comma-separated string of target node identifier(s) to filter.
    no_prepend_pop : bool, optional
        If True, population name is not displayed before sid or tid in the plot. Default is False.
    method : str, optional
        Method for calculating percent connectivity. Options: 'total', 'uni', 'bi'.
        Default is 'total'.
    include_gap : bool, optional
        If True, include gap junctions in analysis. If False, only include chemical synapses.
        Default is True.
    return_dict : bool, optional
        If True, return connection information as a dictionary. Default is False.

    Returns
    -------
    Union[Tuple[Figure, Axes], Dict]
        If return_dict=True, returns a dictionary of connection information.
        Otherwise, returns a tuple of (Figure, Axes) for further customization or saving.

    Raises
    ------
    Exception
        If config is not defined or sources/targets are not defined.

    Examples
    --------
    >>> result = percent_connection_matrix(
    ...     config='config.json',
    ...     sources='PN',
    ...     targets='LN',
    ...     return_dict=True
    ... )
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")

    sources = sources.split(",")
    targets = targets.split(",")
    if sids:
        sids = sids.split(",")
    else:
        sids = []
    if tids:
        tids = tids.split(",")
    else:
        tids = []
    text, num, source_labels, target_labels = util.percent_connections(
        config=config,
        nodes=None,
        edges=None,
        sources=sources,
        targets=targets,
        sids=sids,
        tids=tids,
        prepend_pop=not no_prepend_pop,
        method=method,
        include_gap=include_gap,
    )
    if title is None or title == "":
        title = "Percent Connectivity"

    if return_dict:
        result_dict = plot_connection_info(
            text, num, source_labels, target_labels, title, return_dict=return_dict
        )
        return result_dict
    else:
        return plot_connection_info(text, num, source_labels, target_labels, title)

bmtool.bmplot.connections.probability_connection_matrix(config, nodes=None, edges=None, title=None, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=False, dist_X=True, dist_Y=True, dist_Z=True, bins=8, line_plot=False, verbose=False, include_gap=True)

Generates probability graphs showing connectivity as a function of distance.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
nodes	DataFrame	Pre-loaded node data. If None, will be loaded from config.	None
edges	DataFrame	Pre-loaded edge data. If None, will be loaded from config.	None
title	str	Title for the plot. If None, a default title will be used.	None
sources	str	Comma-separated string of network name(s) to plot.	None
targets	str	Comma-separated string of network name(s) to plot.	None
sids	str	Comma-separated string of source node identifier(s) to filter.	None
tids	str	Comma-separated string of target node identifier(s) to filter.	None
no_prepend_pop	bool	If True, population name is not displayed before sid or tid. Default is False.	False
save_file	str	Path to save the plot. If None, plot is not saved.	required
dist_X	bool	If True, include X distance in calculations. Default is True.	True
dist_Y	bool	If True, include Y distance in calculations. Default is True.	True
dist_Z	bool	If True, include Z distance in calculations. Default is True.	True
bins	int	Number of distance bins for the probability calculation. Default is 8.	8
line_plot	bool	If True, plot lines instead of bars. Default is False.	False
verbose	bool	If True, print debugging information. Default is False.	False
include_gap	bool	If True, include gap junctions in analysis. Default is True.	True

Returns:

Type	Description
None

Raises:

Type	Description
Exception	If config is not defined or sources/targets are not defined.

Notes

This function needs model_template to be defined to work properly.

Source code in bmtool/bmplot/connections.py

def probability_connection_matrix(
    config: str,
    nodes: Optional[pd.DataFrame] = None,
    edges: Optional[pd.DataFrame] = None,
    title: Optional[str] = None,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: bool = False,
    dist_X: bool = True,
    dist_Y: bool = True,
    dist_Z: bool = True,
    bins: int = 8,
    line_plot: bool = False,
    verbose: bool = False,
    include_gap: bool = True,
) -> Tuple[Any, Any]:
    """
    Generates probability graphs showing connectivity as a function of distance.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    nodes : pd.DataFrame, optional
        Pre-loaded node data. If None, will be loaded from config.
    edges : pd.DataFrame, optional
        Pre-loaded edge data. If None, will be loaded from config.
    title : str, optional
        Title for the plot. If None, a default title will be used.
    sources : str, optional
        Comma-separated string of network name(s) to plot.
    targets : str, optional
        Comma-separated string of network name(s) to plot.
    sids : str, optional
        Comma-separated string of source node identifier(s) to filter.
    tids : str, optional
        Comma-separated string of target node identifier(s) to filter.
    no_prepend_pop : bool, optional
        If True, population name is not displayed before sid or tid. Default is False.
    save_file : str, optional
        Path to save the plot. If None, plot is not saved.
    dist_X : bool, optional
        If True, include X distance in calculations. Default is True.
    dist_Y : bool, optional
        If True, include Y distance in calculations. Default is True.
    dist_Z : bool, optional
        If True, include Z distance in calculations. Default is True.
    bins : int, optional
        Number of distance bins for the probability calculation. Default is 8.
    line_plot : bool, optional
        If True, plot lines instead of bars. Default is False.
    verbose : bool, optional
        If True, print debugging information. Default is False.
    include_gap : bool, optional
        If True, include gap junctions in analysis. Default is True.

    Returns
    -------
    None

    Raises
    ------
    Exception
        If config is not defined or sources/targets are not defined.

    Notes
    -----
    This function needs model_template to be defined to work properly.
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    sources = sources.split(",")
    targets = targets.split(",")
    if sids:
        sids = sids.split(",")
    else:
        sids = []
    if tids:
        tids = tids.split(",")
    else:
        tids = []

    throwaway, data, source_labels, target_labels = util.connection_probabilities(
        config=config,
        nodes=None,
        edges=None,
        sources=sources,
        targets=targets,
        sids=sids,
        tids=tids,
        prepend_pop=not no_prepend_pop,
        dist_X=dist_X,
        dist_Y=dist_Y,
        dist_Z=dist_Z,
        num_bins=bins,
        include_gap=include_gap,
    )
    if not data.any():
        return
    if data[0][0] == -1:
        return
    # plot_connection_info(data,source_labels,target_labels,title, save_file=save_file)

    # plt.clf()# clears previous plots
    np.seterr(divide="ignore", invalid="ignore")
    num_src, num_tar = data.shape
    fig, axes = plt.subplots(nrows=num_src, ncols=num_tar, figsize=(12, 12))
    fig.subplots_adjust(hspace=0.5, wspace=0.5)

    for x in range(num_src):
        for y in range(num_tar):
            ns = data[x][y]["ns"]
            bins_data = data[x][y]["bins"]

            XX = bins_data[:-1]
            YY = ns[0] / ns[1]

            if line_plot:
                axes[x, y].plot(XX, YY)
            else:
                axes[x, y].bar(XX, YY)

            if x == num_src - 1:
                axes[x, y].set_xlabel(target_labels[y])
            if y == 0:
                axes[x, y].set_ylabel(source_labels[x])

            if verbose:
                print("Source: [" + source_labels[x] + "] | Target: [" + target_labels[y] + "]")
                print("X:")
                print(XX)
                print("Y:")
                print(YY)

    tt = "Distance Probability Matrix"
    if title:
        tt = title
    st = fig.suptitle(tt, fontsize=14)
    fig.text(0.5, 0.04, "Target", ha="center")
    fig.text(0.04, 0.5, "Source", va="center", rotation="vertical")

    return fig, axes

bmtool.bmplot.connections.convergence_connection_matrix(config, title=None, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=False, convergence=True, method='mean+std', include_gap=True, return_dict=None)

Generates connection plot displaying synaptic convergence data.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
title	str	Title for the plot. If None, a default title will be used.	None
sources	str	Comma-separated string of network name(s) to plot.	None
targets	str	Comma-separated string of network name(s) to plot.	None
sids	str	Comma-separated string of source node identifier(s) to filter.	None
tids	str	Comma-separated string of target node identifier(s) to filter.	None
no_prepend_pop	bool	If True, population name is not displayed before sid or tid. Default is False.	False
save_file	str	Path to save the plot. If None, plot is not saved.	required
convergence	bool	If True, compute convergence; if False, compute divergence. Default is True.	True
method	str	Statistical method for display. Options: 'mean', 'min', 'max', 'stdev', 'mean+std'. Default is 'mean+std'.	'mean+std'
include_gap	bool	If True, include gap junctions in analysis. Default is True.	True
return_dict	bool	If True, return connection information as a dictionary. Default is None.	None

Returns:

Type	Description
Union[Tuple[Figure, Axes], Dict, None]	If return_dict=True, returns a dictionary of connection information. Otherwise, returns a tuple of (Figure, Axes) for further customization or saving.

Raises:

Type	Description
Exception	If config is not defined or sources/targets are not defined.

Examples:

>>> result = convergence_connection_matrix(
...     config='config.json',
...     sources='PN',
...     targets='LN',
...     method='mean+std'
... )

Source code in bmtool/bmplot/connections.py

def convergence_connection_matrix(
    config: str,
    title: Optional[str] = None,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: bool = False,
    convergence: bool = True,
    method: str = "mean+std",
    include_gap: bool = True,
    return_dict: Optional[bool] = None,
) -> Union[Tuple[Any, Any], Dict, None]:
    """
    Generates connection plot displaying synaptic convergence data.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    title : str, optional
        Title for the plot. If None, a default title will be used.
    sources : str, optional
        Comma-separated string of network name(s) to plot.
    targets : str, optional
        Comma-separated string of network name(s) to plot.
    sids : str, optional
        Comma-separated string of source node identifier(s) to filter.
    tids : str, optional
        Comma-separated string of target node identifier(s) to filter.
    no_prepend_pop : bool, optional
        If True, population name is not displayed before sid or tid. Default is False.
    save_file : str, optional
        Path to save the plot. If None, plot is not saved.
    convergence : bool, optional
        If True, compute convergence; if False, compute divergence. Default is True.
    method : str, optional
        Statistical method for display. Options: 'mean', 'min', 'max', 'stdev', 'mean+std'.
        Default is 'mean+std'.
    include_gap : bool, optional
        If True, include gap junctions in analysis. Default is True.
    return_dict : bool, optional
        If True, return connection information as a dictionary. Default is None.

    Returns
    -------
    Union[Tuple[Figure, Axes], Dict, None]
        If return_dict=True, returns a dictionary of connection information.
        Otherwise, returns a tuple of (Figure, Axes) for further customization or saving.

    Raises
    ------
    Exception
        If config is not defined or sources/targets are not defined.

    Examples
    --------
    >>> result = convergence_connection_matrix(
    ...     config='config.json',
    ...     sources='PN',
    ...     targets='LN',
    ...     method='mean+std'
    ... )
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    return divergence_connection_matrix(
        config,
        title,
        sources,
        targets,
        sids,
        tids,
        no_prepend_pop,
        convergence,
        method,
        include_gap=include_gap,
        return_dict=return_dict,
    )

bmtool.bmplot.connections.divergence_connection_matrix(config, title=None, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=False, convergence=False, method='mean+std', include_gap=True, return_dict=None)

Generates connection plot displaying synaptic divergence data.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
title	str	Title for the plot. If None, a default title will be used.	None
sources	str	Comma-separated string of network name(s) to plot.	None
targets	str	Comma-separated string of network name(s) to plot.	None
sids	str	Comma-separated string of source node identifier(s) to filter.	None
tids	str	Comma-separated string of target node identifier(s) to filter.	None
no_prepend_pop	bool	If True, population name is not displayed before sid or tid. Default is False.	False
save_file	str	Path to save the plot. If None, plot is not saved.	required
convergence	bool	If True, compute convergence; if False, compute divergence. Default is False.	False
method	str	Statistical method for display. Options: 'mean', 'min', 'max', 'stdev', 'mean+std'. Default is 'mean+std'.	'mean+std'
include_gap	bool	If True, include gap junctions in analysis. Default is True.	True
return_dict	bool	If True, return connection information as a dictionary. Default is None.	None

Returns:

Type	Description
Union[Tuple[Figure, Axes], Dict, None]	If return_dict=True, returns a dictionary of connection information. Otherwise, returns a tuple of (Figure, Axes) for further customization or saving.

Raises:

Type	Description
Exception	If config is not defined or sources/targets are not defined.

Examples:

>>> result = divergence_connection_matrix(
...     config='config.json',
...     sources='PN',
...     targets='LN',
...     method='mean+std'
... )

Source code in bmtool/bmplot/connections.py

def divergence_connection_matrix(
    config: str,
    title: Optional[str] = None,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: bool = False,
    convergence: bool = False,
    method: str = "mean+std",
    include_gap: bool = True,
    return_dict: Optional[bool] = None,
) -> Union[Tuple[Any, Any], Dict, None]:
    """
    Generates connection plot displaying synaptic divergence data.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    title : str, optional
        Title for the plot. If None, a default title will be used.
    sources : str, optional
        Comma-separated string of network name(s) to plot.
    targets : str, optional
        Comma-separated string of network name(s) to plot.
    sids : str, optional
        Comma-separated string of source node identifier(s) to filter.
    tids : str, optional
        Comma-separated string of target node identifier(s) to filter.
    no_prepend_pop : bool, optional
        If True, population name is not displayed before sid or tid. Default is False.
    save_file : str, optional
        Path to save the plot. If None, plot is not saved.
    convergence : bool, optional
        If True, compute convergence; if False, compute divergence. Default is False.
    method : str, optional
        Statistical method for display. Options: 'mean', 'min', 'max', 'stdev', 'mean+std'.
        Default is 'mean+std'.
    include_gap : bool, optional
        If True, include gap junctions in analysis. Default is True.
    return_dict : bool, optional
        If True, return connection information as a dictionary. Default is None.

    Returns
    -------
    Union[Tuple[Figure, Axes], Dict, None]
        If return_dict=True, returns a dictionary of connection information.
        Otherwise, returns a tuple of (Figure, Axes) for further customization or saving.

    Raises
    ------
    Exception
        If config is not defined or sources/targets are not defined.

    Examples
    --------
    >>> result = divergence_connection_matrix(
    ...     config='config.json',
    ...     sources='PN',
    ...     targets='LN',
    ...     method='mean+std'
    ... )
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    sources = sources.split(",")
    targets = targets.split(",")
    if sids:
        sids = sids.split(",")
    else:
        sids = []
    if tids:
        tids = tids.split(",")
    else:
        tids = []

    syn_info, data, source_labels, target_labels = util.connection_divergence(
        config=config,
        nodes=None,
        edges=None,
        sources=sources,
        targets=targets,
        sids=sids,
        tids=tids,
        prepend_pop=not no_prepend_pop,
        convergence=convergence,
        method=method,
        include_gap=include_gap,
    )

    # data, labels = util.connection_divergence_average(config=config,nodes=nodes,edges=edges,populations=populations)

    if title is None or title == "":
        if method == "min":
            title = "Minimum "
        elif method == "max":
            title = "Maximum "
        elif method == "std":
            title = "Standard Deviation "
        elif method == "mean":
            title = "Mean "
        else:
            title = "Mean + Std "

        if convergence:
            title = title + "Synaptic Convergence"
        else:
            title = title + "Synaptic Divergence"
    if return_dict:
        result_dict = plot_connection_info(
            syn_info,
            data,
            source_labels,
            target_labels,
            title,
            return_dict=return_dict,
        )
        return result_dict
    else:
        return plot_connection_info(
            syn_info, data, source_labels, target_labels, title
        )

bmtool.bmplot.connections.gap_junction_matrix(config, title=None, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=False, method='convergence')

Generates connection plot displaying gap junction data.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
title	str	Title for the plot. If None, a default title will be used.	None
sources	str	Comma-separated string of network name(s) to plot.	None
targets	str	Comma-separated string of network name(s) to plot.	None
sids	str	Comma-separated string of source node identifier(s) to filter.	None
tids	str	Comma-separated string of target node identifier(s) to filter.	None
no_prepend_pop	bool	If True, population name is not displayed before sid or tid. Default is False.	False
save_file	str	Path to save the plot. If None, plot is not saved.	required
method	str	Method for computing gap junction statistics. Options: 'convergence', 'percent'. Default is 'convergence'.	'convergence'

Returns:

Type	Description
None

Raises:

Type	Description
Exception	If config is not defined, sources/targets are not defined, or method is invalid.

Examples:

>>> gap_junction_matrix(
...     config='config.json',
...     sources='PN',
...     targets='LN',
...     method='convergence'
... )

Source code in bmtool/bmplot/connections.py

def gap_junction_matrix(
    config: str,
    title: Optional[str] = None,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: bool = False,
    method: str = "convergence",
) -> Tuple[Any, Any]:
    """
    Generates connection plot displaying gap junction data.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    title : str, optional
        Title for the plot. If None, a default title will be used.
    sources : str, optional
        Comma-separated string of network name(s) to plot.
    targets : str, optional
        Comma-separated string of network name(s) to plot.
    sids : str, optional
        Comma-separated string of source node identifier(s) to filter.
    tids : str, optional
        Comma-separated string of target node identifier(s) to filter.
    no_prepend_pop : bool, optional
        If True, population name is not displayed before sid or tid. Default is False.
    save_file : str, optional
        Path to save the plot. If None, plot is not saved.
    method : str, optional
        Method for computing gap junction statistics. Options: 'convergence', 'percent'.
        Default is 'convergence'.

    Returns
    -------
    None

    Raises
    ------
    Exception
        If config is not defined, sources/targets are not defined, or method is invalid.

    Examples
    --------
    >>> gap_junction_matrix(
    ...     config='config.json',
    ...     sources='PN',
    ...     targets='LN',
    ...     method='convergence'
    ... )
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    if method != "convergence" and method != "percent":
        raise Exception("type must be 'convergence' or 'percent'")
    sources = sources.split(",")
    targets = targets.split(",")
    if sids:
        sids = sids.split(",")
    else:
        sids = []
    if tids:
        tids = tids.split(",")
    else:
        tids = []
    syn_info, data, source_labels, target_labels = util.gap_junction_connections(
        config=config,
        nodes=None,
        edges=None,
        sources=sources,
        targets=targets,
        sids=sids,
        tids=tids,
        prepend_pop=not no_prepend_pop,
        method=method,
    )

    def filter_rows(
        syn_info: np.ndarray,
        data: np.ndarray,
        source_labels: List,
        target_labels: List,
    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, List]:
        """
        Filters out rows in a connectivity matrix that contain only NaN or zero values.

        This function is used to clean up connection matrices by removing rows that have
        no meaningful data, which helps create more informative visualizations of network connectivity.

        Parameters
        ----------
        syn_info : np.ndarray
            Array containing synaptic information corresponding to the data matrix.
        data : np.ndarray
            2D matrix containing connectivity data with rows representing sources
            and columns representing targets.
        source_labels : list
            List of labels for the source populations corresponding to rows in the data matrix.
        target_labels : list
            List of labels for the target populations corresponding to columns in the data matrix.

        Returns
        -------
        tuple
            A tuple containing (syn_info, data, source_labels, target_labels) with invalid rows removed.
        """
        # Identify rows with all NaN or all zeros
        valid_rows = ~np.all(np.isnan(data), axis=1) & ~np.all(data == 0, axis=1)

        # Filter rows based on valid_rows mask
        new_syn_info = syn_info[valid_rows]
        new_data = data[valid_rows]
        new_source_labels = np.array(source_labels)[valid_rows]

        return new_syn_info, new_data, new_source_labels, target_labels

    def filter_rows_and_columns(
        syn_info: np.ndarray,
        data: np.ndarray,
        source_labels: List,
        target_labels: List,
    ) -> Tuple[np.ndarray, np.ndarray, List, List]:
        """
        Filters out both rows and columns in a connectivity matrix that contain only NaN or zero values.

        This function performs a two-step filtering process: first removing rows with no data,
        then transposing the matrix and removing columns with no data (by treating them as rows).
        This creates a cleaner, more informative connectivity matrix visualization.

        Parameters
        ----------
        syn_info : np.ndarray
            Array containing synaptic information corresponding to the data matrix.
        data : np.ndarray
            2D matrix containing connectivity data with rows representing sources
            and columns representing targets.
        source_labels : list
            List of labels for the source populations corresponding to rows in the data matrix.
        target_labels : list
            List of labels for the target populations corresponding to columns in the data matrix.

        Returns
        -------
        tuple
            A tuple containing (syn_info, data, source_labels, target_labels) with both
            invalid rows and columns removed.
        """
        # Filter rows first
        syn_info, data, source_labels, target_labels = filter_rows(
            syn_info, data, source_labels, target_labels
        )

        # Transpose data to filter columns
        transposed_syn_info = np.transpose(syn_info)
        transposed_data = np.transpose(data)
        transposed_source_labels = target_labels
        transposed_target_labels = source_labels

        # Filter columns (by treating them as rows in transposed data)
        (
            transposed_syn_info,
            transposed_data,
            transposed_source_labels,
            transposed_target_labels,
        ) = filter_rows(
            transposed_syn_info, transposed_data, transposed_source_labels, transposed_target_labels
        )

        # Transpose back to original orientation
        filtered_syn_info = np.transpose(transposed_syn_info)
        filtered_data = np.transpose(transposed_data)
        filtered_source_labels = transposed_target_labels  # Back to original source_labels
        filtered_target_labels = transposed_source_labels  # Back to original target_labels

        return filtered_syn_info, filtered_data, filtered_source_labels, filtered_target_labels

    syn_info, data, source_labels, target_labels = filter_rows_and_columns(
        syn_info, data, source_labels, target_labels
    )

    if title is None or title == "":
        title = "Gap Junction"
        if method == "convergence":
            title += " Syn Convergence"
        elif method == "percent":
            title += " Percent Connectivity"
    return plot_connection_info(syn_info, data, source_labels, target_labels, title)

bmtool.bmplot.connections.connection_histogram(config, nodes=None, edges=None, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=True, synaptic_info='0', source_cell=None, target_cell=None, include_gap=True)

Generates histogram of the number of connections individual cells receive from another population.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
nodes	DataFrame	Pre-loaded node data. If None, will be loaded from config.	None
edges	DataFrame	Pre-loaded edge data. If None, will be loaded from config.	None
sources	str	Comma-separated string of network name(s) to plot as sources.	None
targets	str	Comma-separated string of network name(s) to plot as targets.	None
sids	str	Comma-separated string of source node identifier(s) to filter by.	None
tids	str	Comma-separated string of target node identifier(s) to filter by.	None
no_prepend_pop	bool	If True, population name is not prepended to sid or tid. Default is True.	True
synaptic_info	str	Type of synaptic information to display. Default is '0'.	'0'
source_cell	str	Specific source cell type to plot connections from.	None
target_cell	str	Specific target cell type to plot connections onto.	None
include_gap	bool	If True, include gap junctions in analysis. Default is True.	True

Returns:

Type	Description
tuple	(matplotlib.figure.Figure, matplotlib.axes.Axes) containing the histogram.

Source code in bmtool/bmplot/connections.py

def connection_histogram(
    config: str,
    nodes: Optional[pd.DataFrame] = None,
    edges: Optional[pd.DataFrame] = None,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: bool = True,
    synaptic_info: str = "0",
    source_cell: Optional[str] = None,
    target_cell: Optional[str] = None,
    include_gap: bool = True,
) -> Tuple[Any, Any]:
    """
    Generates histogram of the number of connections individual cells receive from another population.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    nodes : pd.DataFrame, optional
        Pre-loaded node data. If None, will be loaded from config.
    edges : pd.DataFrame, optional
        Pre-loaded edge data. If None, will be loaded from config.
    sources : str, optional
        Comma-separated string of network name(s) to plot as sources.
    targets : str, optional
        Comma-separated string of network name(s) to plot as targets.
    sids : str, optional
        Comma-separated string of source node identifier(s) to filter by.
    tids : str, optional
        Comma-separated string of target node identifier(s) to filter by.
    no_prepend_pop : bool, optional
        If True, population name is not prepended to sid or tid. Default is True.
    synaptic_info : str, optional
        Type of synaptic information to display. Default is '0'.
    source_cell : str, optional
        Specific source cell type to plot connections from.
    target_cell : str, optional
        Specific target cell type to plot connections onto.
    include_gap : bool, optional
        If True, include gap junctions in analysis. Default is True.

    Returns
    -------
    tuple
        (matplotlib.figure.Figure, matplotlib.axes.Axes) containing the histogram.
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")

    sources_list = sources.split(",") if sources else []
    targets_list = targets.split(",") if targets else []
    if sids:
        sids_list = sids.split(",")
    else:
        sids_list = []
    if tids:
        tids_list = tids.split(",")
    else:
        tids_list = []

    def connection_pair_histogram(ax=None, **kwargs: Dict) -> None:
        """
        Creates a histogram showing the distribution of connection counts between specific cell types.

        This function is designed to be used with the relation_matrix utility and will only
        create histograms for the specified source and target cell types.

        Parameters
        ----------
        ax : matplotlib.axes.Axes, optional
            The axes object on which to create the histogram. If None, uses current axes.
        kwargs : dict
            Dictionary containing edge data and filtering information.
            - edges: DataFrame containing edge information
            - sid: Column name for source ID type in the edges DataFrame
            - tid: Column name for target ID type in the edges DataFrame
            - source_id: Value to filter edges by source ID type
            - target_id: Value to filter edges by target ID type

        Returns
        -------
        None
        """
        if ax is None:
            ax = plt.gca()
        edges_data = kwargs["edges"]
        source_id_type = kwargs["sid"]
        target_id_type = kwargs["tid"]
        source_id = kwargs["source_id"]
        target_id = kwargs["target_id"]
        if source_id == source_cell and target_id == target_cell:
            temp = edges_data[
                (edges_data[source_id_type] == source_id) & (edges_data[target_id_type] == target_id)
            ]
            if not include_gap:
                gap_col = temp["is_gap_junction"].fillna(False).astype(bool)
                temp = temp[~gap_col]
            node_pairs = temp.groupby("target_node_id")["source_node_id"].count()
            try:
                conn_mean = statistics.mean(node_pairs.values)
                conn_std = statistics.stdev(node_pairs.values)
                conn_median = statistics.median(node_pairs.values)
                label = "mean {:.2f} std {:.2f} median {:.2f}".format(
                    conn_mean, conn_std, conn_median
                )
            except (statistics.StatisticsError, ValueError):  # lazy fix for std not calculated with 1 node
                conn_mean = statistics.mean(node_pairs.values)
                conn_median = statistics.median(node_pairs.values)
                label = "mean {:.2f} median {:.2f}".format(conn_mean, conn_median)
            ax.hist(node_pairs.values, density=False, bins="auto", stacked=True, label=label)
            ax.legend()
            ax.set_xlabel("# of conns from {} to {}".format(source_cell, target_cell))
            ax.set_ylabel("# of cells")
        else:  # dont care about other cell pairs so pass
            pass

    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")

    # Create figure for the histogram
    fig, ax = plt.subplots()

    # Wrapper to pass ax to the connection_pair_histogram function
    def relation_func_wrapper(**kwargs):
        return connection_pair_histogram(ax=ax, **kwargs)

    util.relation_matrix(
        config,
        nodes,
        edges,
        sources_list,
        targets_list,
        sids_list,
        tids_list,
        not no_prepend_pop,
        relation_func=relation_func_wrapper,
        synaptic_info=synaptic_info,
    )

    return fig, ax

bmtool.bmplot.connections.connection_distance(config, sources, targets, source_cell_id, target_id_type, ignore_z=False)

Plots the 3D spatial distribution of target nodes relative to a source node and a histogram of distances from the source node to each target node.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
sources	str	Network name(s) to plot as sources.	required
targets	str	Network name(s) to plot as targets.	required
source_cell_id	int	ID of the source cell for calculating distances to target nodes.	required
target_id_type	str	String to filter target nodes based off the target_query.	required
ignore_z	bool	If True, ignore Z axis when calculating distance. Default is False.	False

Returns:

Type	Description
tuple	Two tuples, each containing (matplotlib.figure.Figure, matplotlib.axes.Axes): - First tuple: 3D/2D scatter plot of node positions - Second tuple: Histogram of distances

Examples:

>>> (fig1, ax1), (fig2, ax2) = connection_distance(
...     config='config.json',
...     sources='PN',
...     targets='LN',
...     source_cell_id=0,
...     target_id_type='LN',
...     ignore_z=False
... )

Source code in bmtool/bmplot/connections.py

def connection_distance(
    config: str,
    sources: str,
    targets: str,
    source_cell_id: int,
    target_id_type: str,
    ignore_z: bool = False,
) -> Tuple[Tuple[Any, Any], Tuple[Any, Any]]:
    """
    Plots the 3D spatial distribution of target nodes relative to a source node
    and a histogram of distances from the source node to each target node.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    sources : str
        Network name(s) to plot as sources.
    targets : str
        Network name(s) to plot as targets.
    source_cell_id : int
        ID of the source cell for calculating distances to target nodes.
    target_id_type : str
        String to filter target nodes based off the target_query.
    ignore_z : bool, optional
        If True, ignore Z axis when calculating distance. Default is False.

    Returns
    -------
    tuple
        Two tuples, each containing (matplotlib.figure.Figure, matplotlib.axes.Axes):
        - First tuple: 3D/2D scatter plot of node positions
        - Second tuple: Histogram of distances

    Examples
    --------
    >>> (fig1, ax1), (fig2, ax2) = connection_distance(
    ...     config='config.json',
    ...     sources='PN',
    ...     targets='LN',
    ...     source_cell_id=0,
    ...     target_id_type='LN',
    ...     ignore_z=False
    ... )
    """
    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    # if source != target:
    # raise Exception("Code is setup for source and target to be the same! Look at source code for function to add feature")

    # Load nodes and edges based on config file
    nodes, edges = util.load_nodes_edges_from_config(config)

    edge_network = sources + "_to_" + targets
    node_network = sources

    # Filter edges to obtain connections originating from the source node
    edge = edges[edge_network]
    edge = edge[edge["source_node_id"] == source_cell_id]
    if target_id_type:
        edge = edge[edge["target_query"].str.contains(target_id_type, na=False)]

    target_node_ids = edge["target_node_id"]

    # Filter nodes to obtain only the target and source nodes
    node = nodes[node_network]
    target_nodes = node.loc[node.index.isin(target_node_ids)]
    source_node = node.loc[node.index == source_cell_id]

    # Calculate distances between source node and each target node
    if ignore_z:
        target_positions = target_nodes[["pos_x", "pos_y"]].values
        source_position = np.array(
            [source_node["pos_x"], source_node["pos_y"]]
        ).ravel()  # Ensure 1D shape
    else:
        target_positions = target_nodes[["pos_x", "pos_y", "pos_z"]].values
        source_position = np.array(
            [source_node["pos_x"], source_node["pos_y"], source_node["pos_z"]]
        ).ravel()  # Ensure 1D shape
    distances = np.linalg.norm(target_positions - source_position, axis=1)

    # Plot positions of source and target nodes in 3D space or 2D
    if ignore_z:
        fig = plt.figure(figsize=(8, 6))
        ax = fig.add_subplot(111)
        ax.scatter(target_nodes["pos_x"], target_nodes["pos_y"], c="blue", label="target cells")
        ax.scatter(source_node["pos_x"], source_node["pos_y"], c="red", label="source cell")
    else:
        fig = plt.figure(figsize=(8, 6))
        ax = fig.add_subplot(111, projection="3d")
        ax.scatter(
            target_nodes["pos_x"],
            target_nodes["pos_y"],
            target_nodes["pos_z"],
            c="blue",
            label="target cells",
        )
        ax.scatter(
            source_node["pos_x"],
            source_node["pos_y"],
            source_node["pos_z"],
            c="red",
            label="source cell",
        )

    # Optional: Add text annotations for distances
    # for i, distance in enumerate(distances):
    #     ax.text(target_nodes['pos_x'].iloc[i], target_nodes['pos_y'].iloc[i], target_nodes['pos_z'].iloc[i],
    #             f'{distance:.2f}', color='black', fontsize=8, ha='center')

    plt.legend()

    # Plot distances in a separate 2D plot
    fig2, ax2 = plt.subplots(figsize=(8, 6))
    ax2.hist(distances, bins=20, color="blue", edgecolor="black")
    ax2.set_xlabel("Distance")
    ax2.set_ylabel("Count")
    ax2.set_title("Distance from Source Node to Each Target Node")
    ax2.grid(True)

    return (fig, ax), (fig2, ax2)

bmtool.bmplot.connections.edge_histogram_matrix(config, sources=None, targets=None, sids=None, tids=None, no_prepend_pop=None, edge_property=None, time=None, time_compare=None, report=None, title=None)

Generates a matrix of histograms showing the distribution of edge properties between populations.

This function creates a grid of histograms where each cell represents the distribution of a specific edge property between source and target populations.

Parameters:

Name	Type	Description	Default
config	str	Path to a BMTK simulation config file.	required
sources	str	Comma-separated list of source network names.	None
targets	str	Comma-separated list of target network names.	None
sids	str	Comma-separated list of source node identifiers to filter by.	None
tids	str	Comma-separated list of target node identifiers to filter by.	None
no_prepend_pop	bool	If True, population names are not prepended to node identifiers.	None
edge_property	str	The edge property to analyze (e.g., 'syn_weight', 'delay').	None
time	int	Time point to analyze from a time series report.	None
time_compare	int	Second time point for comparison with time.	None
report	str	Name of the report to analyze.	None
title	str	Custom title for the plot.	None
save_file	str	Path to save the generated plot.	required

Returns:

Type	Description
tuple	(matplotlib.figure.Figure, matplotlib.axes.Axes) containing the histogram matrix.

Examples:

>>> fig, axes = edge_histogram_matrix(
...     config='config.json',
...     sources='PN',
...     targets='LN',
...     edge_property='syn_weight'
... )

Source code in bmtool/bmplot/connections.py

def edge_histogram_matrix(
    config: str,
    sources: Optional[str] = None,
    targets: Optional[str] = None,
    sids: Optional[str] = None,
    tids: Optional[str] = None,
    no_prepend_pop: Optional[bool] = None,
    edge_property: Optional[str] = None,
    time: Optional[int] = None,
    time_compare: Optional[int] = None,
    report: Optional[str] = None,
    title: Optional[str] = None,

) -> Tuple[Any, Any]:
    """
    Generates a matrix of histograms showing the distribution of edge properties between populations.

    This function creates a grid of histograms where each cell represents the distribution
    of a specific edge property between source and target populations.

    Parameters
    ----------
    config : str
        Path to a BMTK simulation config file.
    sources : str, optional
        Comma-separated list of source network names.
    targets : str, optional
        Comma-separated list of target network names.
    sids : str, optional
        Comma-separated list of source node identifiers to filter by.
    tids : str, optional
        Comma-separated list of target node identifiers to filter by.
    no_prepend_pop : bool, optional
        If True, population names are not prepended to node identifiers.
    edge_property : str, optional
        The edge property to analyze (e.g., 'syn_weight', 'delay').
    time : int, optional
        Time point to analyze from a time series report.
    time_compare : int, optional
        Second time point for comparison with time.
    report : str, optional
        Name of the report to analyze.
    title : str, optional
        Custom title for the plot.
    save_file : str, optional
        Path to save the generated plot.

    Returns
    -------
    tuple
        (matplotlib.figure.Figure, matplotlib.axes.Axes) containing the histogram matrix.

    Examples
    --------
    >>> fig, axes = edge_histogram_matrix(
    ...     config='config.json',
    ...     sources='PN',
    ...     targets='LN',
    ...     edge_property='syn_weight'
    ... )
    """

    if not config:
        raise Exception("config not defined")
    if not sources or not targets:
        raise Exception("Sources or targets not defined")
    targets = targets.split(",")
    if sids:
        sids = sids.split(",")
    else:
        sids = []
    if tids:
        tids = tids.split(",")
    else:
        tids = []

    if time_compare:
        time_compare = int(time_compare)

    data, source_labels, target_labels = util.edge_property_matrix(
        edge_property,
        nodes=None,
        edges=None,
        config=config,
        sources=sources,
        targets=targets,
        sids=sids,
        tids=tids,
        prepend_pop=not no_prepend_pop,
        report=report,
        time=time,
        time_compare=time_compare,
    )

    # Fantastic resource
    # https://stackoverflow.com/questions/7941207/is-there-a-function-to-make-scatterplot-matrices-in-matplotlib
    num_src, num_tar = data.shape
    fig, axes = plt.subplots(nrows=num_src, ncols=num_tar, figsize=(12, 12))
    fig.subplots_adjust(hspace=0.5, wspace=0.5)

    for x in range(num_src):
        for y in range(num_tar):
            axes[x, y].hist(data[x][y])

            if x == num_src - 1:
                axes[x, y].set_xlabel(target_labels[y])
            if y == 0:
                axes[x, y].set_ylabel(source_labels[x])

    tt = edge_property + " Histogram Matrix"
    if title:
        tt = title
    st = fig.suptitle(tt, fontsize=14)
    fig.text(0.5, 0.04, "Target", ha="center")
    fig.text(0.04, 0.5, "Source", va="center", rotation="vertical")
    plt.draw()

    return fig, axes

bmtool.bmplot.connections.distance_delay_plot(simulation_config, source, target, group_by, sid, tid)

Plots the relationship between the distance and delay of connections between nodes in a neural network.

This function loads node and edge data from a simulation configuration file, filters nodes by population, identifies connections (edges) between source and target node populations, calculates the Euclidean distance between connected nodes, and plots the delay as a function of distance.

Parameters:

Name	Type	Description	Default
simulation_config	str	Path to the simulation config file.	required
source	str	The name of the source population in the edge data.	required
target	str	The name of the target population in the edge data.	required
group_by	str	Column name to group nodes by (e.g., population name).	required
sid	str	Identifier for the source group (e.g., 'PN').	required
tid	str	Identifier for the target group (e.g., 'PN').	required

Returns:

Type	Description
tuple	(matplotlib.figure.Figure, matplotlib.axes.Axes) containing the scatter plot.

Examples:

>>> fig, ax = distance_delay_plot(
...     'config.json',
...     'cortex',
...     'cortex',
...     'node_type_id',
...     'E',
...     'E'
... )

Source code in bmtool/bmplot/connections.py

def distance_delay_plot(
    simulation_config: str, source: str, target: str, group_by: str, sid: str, tid: str
) -> Tuple[Any, Any]:
    """
    Plots the relationship between the distance and delay of connections between nodes in a neural network.

    This function loads node and edge data from a simulation configuration file, filters nodes by population,
    identifies connections (edges) between source and target node populations, calculates the Euclidean distance
    between connected nodes, and plots the delay as a function of distance.

    Parameters
    ----------
    simulation_config : str
        Path to the simulation config file.
    source : str
        The name of the source population in the edge data.
    target : str
        The name of the target population in the edge data.
    group_by : str
        Column name to group nodes by (e.g., population name).
    sid : str
        Identifier for the source group (e.g., 'PN').
    tid : str
        Identifier for the target group (e.g., 'PN').

    Returns
    -------
    tuple
        (matplotlib.figure.Figure, matplotlib.axes.Axes) containing the scatter plot.

    Examples
    --------
    >>> fig, ax = distance_delay_plot(
    ...     'config.json',
    ...     'cortex',
    ...     'cortex',
    ...     'node_type_id',
    ...     'E',
    ...     'E'
    ... )
    """
    nodes, edges = util.load_nodes_edges_from_config(simulation_config)
    nodes = nodes[target]
    # node id is index of nodes df
    node_id_source = nodes[nodes[group_by] == sid].index
    node_id_target = nodes[nodes[group_by] == tid].index

    edges = edges[f"{source}_to_{target}"]
    edges = edges[
        edges["source_node_id"].isin(node_id_source) & edges["target_node_id"].isin(node_id_target)
    ]

    stuff_to_plot = []
    for index, row in edges.iterrows():
        try:
            source_node = row["source_node_id"]
            target_node = row["target_node_id"]

            source_pos = nodes.loc[[source_node], ["pos_x", "pos_y", "pos_z"]]
            target_pos = nodes.loc[[target_node], ["pos_x", "pos_y", "pos_z"]]

            distance = np.linalg.norm(source_pos.values - target_pos.values)

            delay = row["delay"]  # This line may raise KeyError
            stuff_to_plot.append([distance, delay])

        except KeyError as e:
            print(f"KeyError: Missing key {e} in either edge properties or node positions.")
        except IndexError as e:
            print(f"IndexError: Node ID {source_node} or {target_node} not found in nodes.")
        except Exception as e:
            print(f"Unexpected error at edge index {index}: {e}")

    fig, ax = plt.subplots()
    ax.scatter([x[0] for x in stuff_to_plot], [x[1] for x in stuff_to_plot])
    ax.set_xlabel("Distance")
    ax.set_ylabel("Delay")
    ax.set_title(f"Distance vs Delay for edge between {sid} and {tid}")

    return fig, ax

bmtool.bmplot.connections.plot_synapse_location(config, source, target, sids, tids, syn_feature='afferent_section_id')

Generates a connectivity matrix showing synaptic distribution across different cell sections.

Note: Excludes gap junctions since they don't have an afferent id stored in the h5 file.

Parameters:

Name	Type	Description	Default
config	str	Path to BMTK config file.	required
source	str	The source BMTK network name.	required
target	str	The target BMTK network name.	required
sids	str	Column name in nodes file containing source population identifiers.	required
tids	str	Column name in nodes file containing target population identifiers.	required
syn_feature	str	Synaptic feature to analyze. Default is 'afferent_section_id'. Options: 'afferent_section_id' or 'afferent_section_pos'.	'afferent_section_id'

Returns:

Type	Description
tuple	(matplotlib.figure.Figure, matplotlib.axes.Axes) containing the plot.

Raises:

Type	Description
ValueError	If required parameters are missing or invalid.
RuntimeError	If template loading or cell instantiation fails.

Examples:

>>> fig, ax = plot_synapse_location(
...     config='config.json',
...     source='LGN',
...     target='cortex',
...     sids='node_type_id',
...     tids='node_type_id'
... )

Source code in bmtool/bmplot/connections.py

def plot_synapse_location(
    config: str,
    source: str,
    target: str,
    sids: str,
    tids: str,
    syn_feature: str = "afferent_section_id",
) -> Tuple[Any, Any]:
    """
    Generates a connectivity matrix showing synaptic distribution across different cell sections.

    Note: Excludes gap junctions since they don't have an afferent id stored in the h5 file.

    Parameters
    ----------
    config : str
        Path to BMTK config file.
    source : str
        The source BMTK network name.
    target : str
        The target BMTK network name.
    sids : str
        Column name in nodes file containing source population identifiers.
    tids : str
        Column name in nodes file containing target population identifiers.
    syn_feature : str, optional
        Synaptic feature to analyze. Default is 'afferent_section_id'.
        Options: 'afferent_section_id' or 'afferent_section_pos'.

    Returns
    -------
    tuple
        (matplotlib.figure.Figure, matplotlib.axes.Axes) containing the plot.

    Raises
    ------
    ValueError
        If required parameters are missing or invalid.
    RuntimeError
        If template loading or cell instantiation fails.

    Examples
    --------
    >>> fig, ax = plot_synapse_location(
    ...     config='config.json',
    ...     source='LGN',
    ...     target='cortex',
    ...     sids='node_type_id',
    ...     tids='node_type_id'
    ... )
    """
    # Validate inputs
    if not all([config, source, target, sids, tids]):
        raise ValueError(
            "Missing required parameters: config, source, target, sids, and tids must be provided"
        )

    # Fix the validation logic - it was using 'or' instead of 'and'
    #if syn_feature not in ["afferent_section_id", "afferent_section_pos"]:
    #    raise ValueError("Currently only syn features supported are afferent_section_id or afferent_section_pos")

    try:
        # Load mechanisms and template
        util.load_templates_from_config(config)
    except Exception as e:
        raise RuntimeError(f"Failed to load templates from config: {str(e)}")

    try:
        # Load node and edge data
        nodes, edges = util.load_nodes_edges_from_config(config)
        if source not in nodes or f"{source}_to_{target}" not in edges:
            raise ValueError(f"Source '{source}' or target '{target}' networks not found in data")

        target_nodes = nodes[target]
        source_nodes = nodes[source]
        edges = edges[f"{source}_to_{target}"]

        # Find edges with NaN values in the specified feature
        nan_edges = edges[edges[syn_feature].isna()]
        # Print information about removed edges
        if not nan_edges.empty:
            unique_indices = sorted(list(set(nan_edges.index.tolist())))
            print(f"Removing {len(nan_edges)} edges with missing {syn_feature}")
            print(f"Unique indices removed: {unique_indices}")

        # Filter out edges with NaN values in the specified feature
        edges = edges[edges[syn_feature].notna()]

    except Exception as e:
        raise RuntimeError(f"Failed to load nodes and edges: {str(e)}")

    # Map identifiers while checking for missing values
    edges["target_model_template"] = edges["target_node_id"].map(target_nodes["model_template"])
    edges["target_pop_name"] = edges["target_node_id"].map(target_nodes[tids])
    edges["source_pop_name"] = edges["source_node_id"].map(source_nodes[sids])

    if edges["target_model_template"].isnull().any():
        print("Warning: Some target nodes missing model template")
    if edges["target_pop_name"].isnull().any():
        print("Warning: Some target nodes missing population name")
    if edges["source_pop_name"].isnull().any():
        print("Warning: Some source nodes missing population name")

    # Get unique populations
    source_pops = edges["source_pop_name"].unique()
    target_pops = edges["target_pop_name"].unique()

    # Initialize matrices
    num_connections = np.zeros((len(source_pops), len(target_pops)))
    text_data = np.empty((len(source_pops), len(target_pops)), dtype=object)

    # Create mappings for indices
    source_pop_to_idx = {pop: idx for idx, pop in enumerate(source_pops)}
    target_pop_to_idx = {pop: idx for idx, pop in enumerate(target_pops)}

    # Cache for section mappings to avoid recreating cells
    section_mappings = {}

    # Calculate connectivity statistics
    for source_pop in source_pops:
        for target_pop in target_pops:
            # Filter edges for this source-target pair
            filtered_edges = edges[
                (edges["source_pop_name"] == source_pop) & (edges["target_pop_name"] == target_pop)
            ]

            source_idx = source_pop_to_idx[source_pop]
            target_idx = target_pop_to_idx[target_pop]

            if len(filtered_edges) == 0:
                num_connections[source_idx, target_idx] = 0
                text_data[source_idx, target_idx] = "No connections"
                continue

            total_connections = len(filtered_edges)
            target_model_template = filtered_edges["target_model_template"].iloc[0]

            try:
                # Get or create section mapping for this model
                if target_model_template not in section_mappings:
                    cell_class_name = (
                        target_model_template.split(":")[1]
                        if ":" in target_model_template
                        else target_model_template
                    )
                    cell = getattr(h, cell_class_name)()

                    # Create section mapping
                    section_mapping = {}
                    for idx, sec in enumerate(cell.all):
                        section_mapping[idx] = sec.name().split(".")[-1]  # Clean name
                    section_mappings[target_model_template] = section_mapping

                section_mapping = section_mappings[target_model_template]

                # Calculate section distribution
                section_counts = filtered_edges[syn_feature].value_counts()
                section_percentages = (section_counts / total_connections * 100).round(1)

                # Format section distribution text - show all sections
                section_display = []
                for section_id, percentage in section_percentages.items():
                    section_name = section_mapping.get(section_id, f"sec_{section_id}")
                    section_display.append(f"{section_name}:{percentage}%")


                num_connections[source_idx, target_idx] = total_connections
                text_data[source_idx, target_idx] = "\n".join(section_display)

            except Exception as e:
                print(f"Warning: Error processing {target_model_template}: {str(e)}")
                num_connections[source_idx, target_idx] = total_connections
                text_data[source_idx, target_idx] = "Feature info N/A"

    # Create the plot
    title = f"Synaptic Distribution by {syn_feature.replace('_', ' ').title()}: {source} to {target}"
    fig, ax = plot_connection_info(
        text=text_data,
        num=num_connections,
        source_labels=list(source_pops),
        target_labels=list(target_pops),
        title=title,
        syn_info="1",
    )
    return fig, ax