0
# Utilities and Extensions
1

2
Additional functionality including file writing, filtering, stimulus waveform handling, and plotting functions. These utilities extend the core pyabf functionality for specialized use cases.
3

4
## Capabilities
5

6
### ABF File Writing
7

8
Functions for creating new ABF files from data arrays.
9

10
```python { .api }
11
from pyabf import abfWriter
12

13
def writeABF1(
14
    sweepData: np.ndarray,
15
    filename: Union[str, pathlib.Path],
16
    sampleRateHz: float,
17
    units: str = 'pA'
18
) -> None:
19
    """
20
    Write data to a new ABF1 format file.
21
    
22
    Parameters:
23
    - sweepData: 2D numpy array where each row is a sweep
24
                Shape: (number_of_sweeps, points_per_sweep)
25
    - filename: Output file path
26
    - sampleRateHz: Data acquisition sample rate in Hz
27
    - units: Data units (e.g., 'pA', 'mV', 'nA')
28
    
29
    Note: Creates ABF1 format files compatible with older analysis software
30
    """
31
```
32

33
### Signal Filtering
34

35
Functions for applying digital filters to ABF data.
36

37
```python { .api }
38
from pyabf import filter
39

40
def remove(abf) -> None:
41
    """
42
    Remove any applied filtering from ABF object.
43
    
44
    Parameters:
45
    - abf: ABF object to remove filtering from
46
    
47
    Note: Modifies the ABF object in place, returns None
48
    """
49

50
def gaussian(abf, sigmaMs: float = 5, channel: int = 0) -> None:
51
    """
52
    Apply Gaussian smoothing filter to ABF data.
53
    
54
    Parameters:
55
    - abf: ABF object to filter
56
    - sigmaMs: Filter sigma in milliseconds (controls smoothing strength)
57
    - channel: Channel number to filter
58
    
59
    Note: Modifies the ABF object's data in place, returns None
60
    """
61
```
62

63
### Stimulus Waveform Handling
64

65
Classes and functions for working with stimulus waveforms and protocols.
66

67
```python { .api }
68
from pyabf import stimulus
69

70
class Stimulus:
71
    def __init__(self, abf, channel: int):
72
        """
73
        Create stimulus waveform handler for specified channel.
74
        
75
        Parameters:
76
        - abf: ABF object
77
        - channel: DAC channel number
78
        """
79
    
80
    def stimulusWaveform(self, stimulusSweep: int = 0) -> np.ndarray:
81
        """
82
        Generate stimulus waveform for specified sweep.
83
        
84
        Parameters:
85
        - stimulusSweep: Sweep number to generate waveform for
86
        
87
        Returns:
88
        numpy array containing the stimulus waveform
89
        """
90

91
def findStimulusWaveformFile(abf, channel: int = 0) -> Union[str, None]:
92
    """
93
    Find the stimulus waveform file associated with an ABF.
94
    
95
    Parameters:
96
    - abf: ABF object
97
    - channel: DAC channel number
98
    
99
    Returns:
100
    Path to stimulus file if found, None otherwise
101
    """
102

103
def stimulusWaveformFromFile(abf, channel: int = 0) -> Union[np.ndarray, None]:
104
    """
105
    Load stimulus waveform from associated file.
106
    
107
    Parameters:
108
    - abf: ABF object  
109
    - channel: DAC channel number
110
    
111
    Returns:
112
    numpy array with stimulus waveform, or None if not found
113
    """
114
```
115

116
### Name Resolution Utilities
117

118
Functions for converting numeric codes to human-readable names.
119

120
```python { .api }
121
from pyabf import names
122

123
def getDigitizerName(digitizerNumber: int) -> str:
124
    """
125
    Get digitizer name from numeric code.
126
    
127
    Parameters:
128
    - digitizerNumber: Numeric digitizer identifier
129
    
130
    Returns:
131
    Human-readable digitizer name
132
    """
133

134
def getTelegraphName(telegraphNumber: int) -> str:
135
    """
136
    Get telegraph amplifier name from numeric code.
137
    
138
    Parameters:
139
    - telegraphNumber: Numeric telegraph identifier
140
    
141
    Returns:
142
    Human-readable telegraph amplifier name
143
    """
144

145
def getUserListParameterName(paramNumber: int, epochCount: int = 50) -> str:
146
    """
147
    Get user list parameter name from numeric code.
148
    
149
    Parameters:
150
    - paramNumber: Parameter number
151
    - epochCount: Number of epochs (default 50)
152
    
153
    Returns:
154
    Human-readable parameter name
155
    """
156
```
157

158
### Plotting Functions (DEPRECATED)
159

160
Legacy plotting functions using matplotlib. These are marked as obsolete and should not be used in new code.
161

162
```python { .api }
163
from pyabf import plot
164
import warnings
165
warnings.warn("abf.plot is obsolete and should not be used")
166

167
def sweepDataRange(
168
    abf, 
169
    fraction: float = 1, 
170
    sweepNumber: int = 0, 
171
    channel: int = 0
172
) -> float:
173
    """
174
    Calculate data range for sweep (DEPRECATED).
175
    
176
    Returns magnitude of range between min and max points in sweep.
177
    Use numpy functions directly instead.
178
    """
179

180
def sweeps(
181
    abf,
182
    sweepNumbers: Union[List[int], None] = None,
183
    continuous: bool = False,
184
    offsetXsec: float = 0,
185
    **kwargs
186
) -> None:
187
    """
188
    Plot multiple sweeps (DEPRECATED).
189
    
190
    Create your own plotting functions using matplotlib directly.
191
    """
192
```
193

194
### Usage Examples
195

196
```python
197
import pyabf
198
import numpy as np
199

200
# File writing example
201
data = np.random.randn(10, 1000)  # 10 sweeps, 1000 points each
202
pyabf.abfWriter.writeABF1(
203
    sweepData=data,
204
    filename="synthetic_data.abf", 
205
    sampleRateHz=10000,
206
    units="pA"
207
)
208

209
# Signal filtering
210
abf = pyabf.ABF("noisy_recording.abf")
211
print(f"Original data shape: {abf.getAllYs().shape}")
212

213
# Apply Gaussian smoothing (modifies ABF in place)
214
pyabf.filter.gaussian(abf, sigmaMs=2, channel=0)
215
abf.setSweep(0)
216
print(f"Filtered sweep 0 max: {np.max(abf.sweepY):.2f}")
217

218
# Remove filtering (modifies ABF in place)
219
pyabf.filter.remove(abf)
220

221
# Stimulus waveform handling
222
stim = pyabf.stimulus.Stimulus(abf, channel=0)
223
waveform = stim.stimulusWaveform(stimulusSweep=0)
224
if waveform is not None:
225
    print(f"Stimulus waveform length: {len(waveform)}")
226

227
# Find external stimulus file
228
stim_file = pyabf.stimulus.findStimulusWaveformFile(abf, channel=0)
229
if stim_file:
230
    print(f"Found stimulus file: {stim_file}")
231
    ext_waveform = pyabf.stimulus.stimulusWaveformFromFile(abf, channel=0)
232

233
# Name resolution
234
digitizer = pyabf.names.getDigitizerName(1)
235
telegraph = pyabf.names.getTelegraphName(0)
236
print(f"Digitizer: {digitizer}")
237
print(f"Telegraph: {telegraph}")
238

239
# Hardware parameter names
240
param_name = pyabf.names.getUserListParameterName(5)
241
print(f"Parameter 5: {param_name}")
242
```
243

244
## Waveform Generation
245

246
Advanced waveform generation capabilities for creating custom stimulus protocols.
247

248
```python { .api }
249
from pyabf import waveform
250

251
class Epoch:
252
    """
253
    Represents a single epoch in a stimulus waveform.
254
    """
255
    
256
    @property
257
    def epochLetter(self) -> str:
258
        """Single letter identifier for the epoch type."""
259
    
260
    @property
261
    def epochTypeStr(self) -> str:
262
        """Human-readable epoch type description."""
263

264
class EpochSweepWaveform:
265
    """
266
    Container for waveform data needed to generate stimulus for a single sweep.
267
    """
268
    
269
    def __init__(self):
270
        """Initialize empty epoch sweep waveform."""
271
    
272
    def addEpoch(
273
        self,
274
        pt1: int, pt2: int,
275
        level: float,
276
        epochType: int,
277
        pulseWidth: float,
278
        pulsePeriod: float,
279
        digitalState: int = 0
280
    ) -> None:
281
        """
282
        Add an epoch to the waveform.
283
        
284
        Parameters:
285
        - pt1, pt2: Start and end points for the epoch
286
        - level: Amplitude level for this epoch
287
        - epochType: Type of epoch (step, ramp, pulse, etc.)
288
        - pulseWidth: Width of pulses in this epoch
289
        - pulsePeriod: Period between pulses
290
        - digitalState: Digital output state
291
        """
292
    
293
    def getWaveform(self) -> np.ndarray:
294
        """
295
        Generate the complete waveform array.
296
        
297
        Returns:
298
        numpy array containing the stimulus waveform
299
        """
300
    
301
    def getDigitalWaveform(self, digitalChannel: int) -> np.ndarray:
302
        """
303
        Generate digital output waveform for specified channel.
304
        
305
        Parameters:
306
        - digitalChannel: Digital channel number
307
        
308
        Returns:
309
        numpy array of digital states (0 or 1)
310
        """
311
```
312

313
## Best Practices
314

315
### File Writing
316

317
```python
318
# Always specify appropriate units
319
data_pA = measurement_data * 1e12  # Convert to pA
320
pyabf.abfWriter.writeABF1(data_pA, "output.abf", 20000, units="pA")
321

322
# For voltage data
323
data_mV = voltage_data * 1000  # Convert to mV  
324
pyabf.abfWriter.writeABF1(data_mV, "voltage.abf", 10000, units="mV")
325
```
326

327
### Filtering
328

329
```python
330
# Apply conservative filtering to avoid distorting signals
331
# Sigma of 1-2 ms is typically appropriate for most recordings
332
filtered_abf = pyabf.filter.gaussian(abf, sigmaMs=1.5)
333

334
# Always keep a reference to the original unfiltered data
335
original_abf = pyabf.ABF("data.abf")  # Reload if needed
336
```