baseUserAnalysis

Discover, register, and run SanPy user-analysis plugins.

Attributes

Classes

baseUserAnalysis

Create a userAnalysis object after bAnalysis has been analyzed with the core analysis results.

Source code in sanpy/user_analysis/baseUserAnalysis.py

class baseUserAnalysis:
    """Create a userAnalysis object after bAnalysis has been analyzed with the core analysis results."""

    def __init__(self, ba: "sanpy.bAnalysis"):
        self._myAnalysis: sanpy.bAnalysis = ba

        self._userStatNames: list[str] = []

        self.defineUserStats()

    def _getUserStatNames(self) -> tuple[str, ...]:
        """Return internal names of results produced by this analysis."""
        return tuple(self._userStatNames)

    def defineUserStats(self):
        """Derived classes add each stat with addUserStat().

        See Also
        --------
        addUserStat
        """
        pass

    def addUserStat(
        self,
        humanName: str,
        internalName: str,
        *,
        showInPlotMenu: bool,
        isCategorical: bool,
        category: AnalysisResultCategory = AnalysisResultCategory.CUSTOM,
        valueType: str,
        default: Any,
        units: str,
        axisLabel: str,
        description: str,
    ) -> bool:
        """Register a user statistic for analysis and presentation.

        Args:
            humanName: Human-readable statistic name.
            internalName: Internal dataframe-column name without spaces or
                punctuation.
            showInPlotMenu: Whether X/Y statistic selectors show the result.
            isCategorical: Whether plots interpret values as discrete groups.
            category: Presentation category stored in the runtime result
                schema.
            valueType: Runtime value type name, such as ``"float"``.
            default: Default value for the result.
            units: Physical or logical units.
            axisLabel: Plot-axis label.
            description: Human-readable explanation.

        Returns:
            ``True`` when the definition was registered or was already
            registered identically; ``False`` when a conflicting definition
            was rejected.
        """
        from sanpy.bAnalysisResults import register_analysis_result

        registered = register_analysis_result(
            internalName,
            category=category,
            value_type=valueType,
            default=default,
            units=units,
            axis_label=axisLabel,
            show_in_plot_menu=showInPlotMenu,
            is_categorical=isCategorical,
            description=description,
        )
        if internalName not in self._userStatNames:
            self._userStatNames.append(internalName)
        return registered

    @property
    def ba(self):
        """Get the underlying [sanpy.bAnalysis][sanpy.bAnalysis] object"""
        return self._myAnalysis

    def getSweepX(self):
        """Get the x-axis of a recording."""
        return self.ba.fileLoader.sweepX

    def getSweepY(self):
        """Get the y-axis of a recording."""
        return self.ba.fileLoader.sweepY

    def getSweepC(self):
        """Get the DAC axis of a recording."""
        return self.ba.fileLoader.sweepC

    def getFilteredVm(self):
        return self.ba.fileLoader.sweepY_filtered

    def setSpikeValue(self, spikeIdx, theKey, theVal):
        """Set the value of a spike key.

        Parameters
        ----------
        spikeIdx : int
            The spike index , 0 based.
        theKey : str
            Name of the user defined internal name.
        theVal :
            The value for the key, can be almost any type like
            (float, int, bool, dict, list)

        Raises
        ------
        KeyError
            If theKey is not a key in analysis results.
        IndexError
            If spikeIdx is beyond number of spikes -1.
        """
        try:
            self.ba.spikeDict[spikeIdx][theKey] = theVal
        except (KeyError) as e:
            logger.error(f'User internal stat does not exist "{theKey}"')
        except (IndexError) as e:
            logger.error(
                f"spikeIdx {spikeIdx} is out of range, max value is {self.ba.numSpikes}"
            )

    def getSpikeValue(self, spikeIdx, theKey):
        """Get a single spike analysis result from key.

        Parameters
        ----------
        spikeIdx : int
            The spike index, 0 based.
        theKey : str
            Name of the analysis result defined internal name.

        Raises
        ------
        KeyError
            If theKey is not a key in analysis results.
        IndexError
            If spikeIdx is beyond number of spikes -1.
        """
        try:
            theRet = self.ba.spikeDict[spikeIdx][theKey]
            return theRet
        except KeyError as e:
            logger.error(f'User internal stat does not exist "{theKey}"')
        except IndexError as e:
            logger.error(
                f"spikeIdx {spikeIdx} is out of range, max value is {self.ba.numSpikes}"
            )

    def run(self):
        """Run user analysis. Calculate values for each new user stat."""

Attributes

ba property

Get the underlying sanpy.bAnalysis object

Methods:

addUserStat(humanName, internalName, *, showInPlotMenu, isCategorical, category=AnalysisResultCategory.CUSTOM, valueType, default, units, axisLabel, description)

Register a user statistic for analysis and presentation.

Args: humanName: Human-readable statistic name. internalName: Internal dataframe-column name without spaces or punctuation. showInPlotMenu: Whether X/Y statistic selectors show the result. isCategorical: Whether plots interpret values as discrete groups. category: Presentation category stored in the runtime result schema. valueType: Runtime value type name, such as "float". default: Default value for the result. units: Physical or logical units. axisLabel: Plot-axis label. description: Human-readable explanation.

Returns: True when the definition was registered or was already registered identically; False when a conflicting definition was rejected.

Source code in sanpy/user_analysis/baseUserAnalysis.py

def addUserStat(
    self,
    humanName: str,
    internalName: str,
    *,
    showInPlotMenu: bool,
    isCategorical: bool,
    category: AnalysisResultCategory = AnalysisResultCategory.CUSTOM,
    valueType: str,
    default: Any,
    units: str,
    axisLabel: str,
    description: str,
) -> bool:
    """Register a user statistic for analysis and presentation.

    Args:
        humanName: Human-readable statistic name.
        internalName: Internal dataframe-column name without spaces or
            punctuation.
        showInPlotMenu: Whether X/Y statistic selectors show the result.
        isCategorical: Whether plots interpret values as discrete groups.
        category: Presentation category stored in the runtime result
            schema.
        valueType: Runtime value type name, such as ``"float"``.
        default: Default value for the result.
        units: Physical or logical units.
        axisLabel: Plot-axis label.
        description: Human-readable explanation.

    Returns:
        ``True`` when the definition was registered or was already
        registered identically; ``False`` when a conflicting definition
        was rejected.
    """
    from sanpy.bAnalysisResults import register_analysis_result

    registered = register_analysis_result(
        internalName,
        category=category,
        value_type=valueType,
        default=default,
        units=units,
        axis_label=axisLabel,
        show_in_plot_menu=showInPlotMenu,
        is_categorical=isCategorical,
        description=description,
    )
    if internalName not in self._userStatNames:
        self._userStatNames.append(internalName)
    return registered

defineUserStats()

Derived classes add each stat with addUserStat().

See Also

addUserStat

Source code in sanpy/user_analysis/baseUserAnalysis.py

def defineUserStats(self):
    """Derived classes add each stat with addUserStat().

    See Also
    --------
    addUserStat
    """
    pass

getSpikeValue(spikeIdx, theKey)

Get a single spike analysis result from key.

Parameters:

Name	Type	Description	Default
spikeIdx	int	The spike index, 0 based.	required
theKey	str	Name of the analysis result defined internal name.	required

Raises:

Type	Description
KeyError	If theKey is not a key in analysis results.
IndexError	If spikeIdx is beyond number of spikes -1.

Source code in sanpy/user_analysis/baseUserAnalysis.py

def getSpikeValue(self, spikeIdx, theKey):
    """Get a single spike analysis result from key.

    Parameters
    ----------
    spikeIdx : int
        The spike index, 0 based.
    theKey : str
        Name of the analysis result defined internal name.

    Raises
    ------
    KeyError
        If theKey is not a key in analysis results.
    IndexError
        If spikeIdx is beyond number of spikes -1.
    """
    try:
        theRet = self.ba.spikeDict[spikeIdx][theKey]
        return theRet
    except KeyError as e:
        logger.error(f'User internal stat does not exist "{theKey}"')
    except IndexError as e:
        logger.error(
            f"spikeIdx {spikeIdx} is out of range, max value is {self.ba.numSpikes}"
        )

getSweepC()

Get the DAC axis of a recording.

Source code in sanpy/user_analysis/baseUserAnalysis.py

def getSweepC(self):
    """Get the DAC axis of a recording."""
    return self.ba.fileLoader.sweepC

getSweepX()

Get the x-axis of a recording.

Source code in sanpy/user_analysis/baseUserAnalysis.py

def getSweepX(self):
    """Get the x-axis of a recording."""
    return self.ba.fileLoader.sweepX

getSweepY()

Get the y-axis of a recording.

Source code in sanpy/user_analysis/baseUserAnalysis.py

def getSweepY(self):
    """Get the y-axis of a recording."""
    return self.ba.fileLoader.sweepY

run()

Run user analysis. Calculate values for each new user stat.

Source code in sanpy/user_analysis/baseUserAnalysis.py

def run(self):
    """Run user analysis. Calculate values for each new user stat."""

setSpikeValue(spikeIdx, theKey, theVal)

Set the value of a spike key.

Parameters:

Name	Type	Description	Default
spikeIdx	int	The spike index , 0 based.	required
theKey	str	Name of the user defined internal name.	required
theVal		The value for the key, can be almost any type like (float, int, bool, dict, list)	required

Raises:

Type	Description
KeyError	If theKey is not a key in analysis results.
IndexError	If spikeIdx is beyond number of spikes -1.

Source code in sanpy/user_analysis/baseUserAnalysis.py

def setSpikeValue(self, spikeIdx, theKey, theVal):
    """Set the value of a spike key.

    Parameters
    ----------
    spikeIdx : int
        The spike index , 0 based.
    theKey : str
        Name of the user defined internal name.
    theVal :
        The value for the key, can be almost any type like
        (float, int, bool, dict, list)

    Raises
    ------
    KeyError
        If theKey is not a key in analysis results.
    IndexError
        If spikeIdx is beyond number of spikes -1.
    """
    try:
        self.ba.spikeDict[spikeIdx][theKey] = theVal
    except (KeyError) as e:
        logger.error(f'User internal stat does not exist "{theKey}"')
    except (IndexError) as e:
        logger.error(
            f"spikeIdx {spikeIdx} is out of range, max value is {self.ba.numSpikes}"
        )

Functions:

runAllUserAnalysis(ba, verbose=False)

Run all user defined analysis.

Notes

Called at end of sanpy.bAnalysis.detect()

Source code in sanpy/user_analysis/baseUserAnalysis.py

def runAllUserAnalysis(ba, verbose=False):
    """Run all user defined analysis.

    Notes
    -----
    Called at end of sanpy.bAnalysis.detect()
    """

    # step through each
    objList = _getObjectList()  # list of dict

    if verbose:
        logger.info(f"objList: {objList}")
    for obj in objList:
        # instantiate and call run (will add values for stats
        # was this
        # userObj = obj(ba)
        # userObj.run()

        try:
            # instantiate a user object
            userObj = obj["constructor"](ba)

            # run the analysis
            userObj.run()  # run the analysis and append to actual ba object
        except Exception as e:
            logger.error(f"Exception in running user defined analysis: {e}")
            logger.error(traceback.format_exc())