Skip to content

Commit 7b189ad

Browse files
fronzbotfronzbot
authored
Merge pull request #107 from fronzbot/update-docstrings
Updated docstrings
2 parents 599f727 + 048899d commit 7b189ad

File tree

7 files changed

+322
-35
lines changed

7 files changed

+322
-35
lines changed

‎adc_eval/adcs/basic.py‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,6 @@ class ADC:
1414
"""
1515
Generic ADC Class.
1616
17-
...
18-
1917
Parameters
2018
----------
2119
nbits : int, default=8

‎adc_eval/eval/calc.py‎

Lines changed: 96 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,90 @@
44

55

66
def db_to_pow(value, places=3):
7-
"""Convert dBW to W."""
7+
"""
8+
Convert dBW to W.
9+
10+
Parameters
11+
----------
12+
value : float or ndarray
13+
Value to convert to power, in dBW.
14+
places : int, optional
15+
Number of places to round output value to. Default is 3.
16+
17+
Returns
18+
-------
19+
float or ndarray
20+
Returns either the rounded and converted value, or the ndarray
21+
"""
822
if isinstance(value, np.ndarray):
923
return np.round(10 ** (0.1 * value), places)
1024
return round(10 ** (0.1 * value), places)
1125

1226

1327
def dBW(value, places=1):
14-
"""Convert to dBW."""
28+
"""
29+
Convert to dBW.
30+
31+
Parameters
32+
----------
33+
value : float or ndarray
34+
Value to convert to dBW, in W.
35+
places : int, optional
36+
Number of places to round output value to. Default is 1.
37+
38+
Returns
39+
-------
40+
float or ndarray
41+
Returns either the rounded and converted value, or the ndarray
42+
"""
1543
if isinstance(value, np.ndarray):
1644
return np.round(10 * np.log10(value), places)
1745
return round(10 * np.log10(value), places)
1846

1947

2048
def enob(sndr, places=1):
21-
"""Return ENOB for given SNDR."""
49+
"""
50+
Return ENOB for given SNDR.
51+
52+
Parameters
53+
----------
54+
sndr : float
55+
SNDR value in dBW to convert to ENOB.
56+
places : int, optional
57+
Number of places to round output value to. Default is 1.
58+
59+
Returns
60+
-------
61+
float or ndarray
62+
Returns either the rounded and converted value, or the ndarray
63+
"""
2264
return round((sndr - 1.76) / 6.02, places)
2365

2466

25-
def sndr_sfdr(spectrum, freq, fs, nfft, leak, full_scale=0):
26-
"""Get SNDR and SFDR."""
27-
67+
def sndr_sfdr(spectrum, freq, fs, nfft, leak=0, full_scale=0):
68+
"""
69+
Get SNDR and SFDR.
70+
71+
Parameters
72+
----------
73+
spectrum : ndarray
74+
Power spectrum as ndarray in units of Watts.
75+
freq : ndarray
76+
Array of frequencies for the input power spectrum.
77+
fs : float
78+
Sample frequency of power spectrum in Hz.
79+
nfft : int
80+
Number of samples in the FFT.
81+
leak : int, optional
82+
Number of leakage bins to consider when looking for peaks. Default is 0.
83+
full_scale : float, optional
84+
Full scale reference value for spectrum in Watts.
85+
86+
Returns
87+
-------
88+
dict
89+
Returns a dictionary of computed stats.
90+
"""
2891
# Zero the DC bin
2992
for i in range(0, leak + 1):
3093
spectrum[i] = 0
@@ -81,7 +144,33 @@ def sndr_sfdr(spectrum, freq, fs, nfft, leak, full_scale=0):
81144

82145

83146
def find_harmonics(spectrum, freq, nfft, bin_sig, psig, harms=5, leak=20, fscale=1e6):
84-
"""Get the harmonic contents of the data."""
147+
"""
148+
Get the harmonic contents of the data.
149+
150+
Parameters
151+
----------
152+
spectrum : ndarray
153+
Power spectrum as ndarray in units of Watts.
154+
freq : ndarray
155+
Array of frequencies for the input power spectrum.
156+
nfft : int
157+
Number of samples in the FFT.
158+
bin_sig : int
159+
Frequency bin of the dominant signal.
160+
psig : float
161+
Power of dominant signal in spectrum.
162+
harms : int, optional
163+
Number of input harmonics to calculate. Default is 5.
164+
leak : int, optional
165+
Number of leakage bins to look at when finding harmonics. Default is 20.
166+
fscale : float, optional
167+
Value to scale frequencies by in Hz. Default is 1MHz.
168+
169+
Returns
170+
-------
171+
dict
172+
Returns a dictionary of computed stats.
173+
"""
85174
harm_stats = {"harm": {}}
86175
harm_index = 2
87176
for harm in bin_sig * np.arange(2, harms + 1):

‎adc_eval/eval/simulate.py‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,28 @@
55

66

77
class Simulator:
8-
"""Class for handling simulation functions."""
8+
"""
9+
Class for handling simulation functions.
10+
11+
Parameters
12+
----------
13+
adc_obj : ADC.__class__
14+
An ADC object from the adc_eval.eval.adc class list.
15+
xarray : ndarray
16+
Input signal array to simulate the adc_obj with.
17+
18+
19+
Attributes
20+
----------
21+
out : ndarray of ADC output values.
22+
adc : Reference to the input adc_obj.
23+
vin : xarray with global signal errors included as set by adj_obj.
24+
25+
Methods
26+
-------
27+
run
28+
29+
"""
930

1031
def __init__(self, adc_obj, xarray):
1132
"""Initialize the simulator class."""
@@ -19,7 +40,7 @@ def out(self):
1940
return np.array(self.dval)
2041

2142
def calc_error(self, vin):
22-
"""Using the adc obj, calculates global signal error."""
43+
"""Using the adc_obj, calculates global signal error before simulation."""
2344
vinx = vin
2445

2546
# First calculate gain error

‎adc_eval/eval/spectrum.py‎

Lines changed: 125 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,25 @@
55
from adc_eval.eval import calc
66

77

8-
def calc_psd(data, fs, nfft=2**12):
9-
"""Calculate the PSD using the Bartlett method."""
8+
def calc_psd(data, fs=1, nfft=2**12):
9+
"""
10+
Calculate the PSD using the Bartlett method.
11+
12+
Parameters
13+
----------
14+
data : ndarray
15+
Time-series input data.
16+
fs : float, optional
17+
Sample frequency of the input time series data in Hz. Default is 1Hz.
18+
nfft : int, optional
19+
Number of FFT samples to use for PSD calculation. Default is 2^12.
20+
21+
Returns
22+
-------
23+
list
24+
[freq_ss, psd_ss, freq_ds, psd_ds]
25+
List containing single and double-sided PSDs along with frequncy array.
26+
"""
1027
nwindows = max(1, int(np.floor(len(data) / nfft)))
1128
nfft = int(nfft)
1229
xs = data[0 : int(nwindows * nfft)]
@@ -29,15 +46,49 @@ def calc_psd(data, fs, nfft=2**12):
2946

3047

3148
def get_spectrum(data, fs=1, nfft=2**12, single_sided=True):
32-
"""Get the power spectrum for an input signal."""
49+
"""
50+
Get the power spectrum for an input signal.
51+
52+
Parameters
53+
----------
54+
data : ndarray
55+
Time-series input data.
56+
fs : float, optional
57+
Sample frequency of the input time series data in Hz. Default is 1Hz.
58+
nfft : int, optional
59+
Number of FFT samples to use for PSD calculation. Default is 2^12.
60+
single_sided : bool, optional
61+
Set to `True` for single-sided spectrum or `False` for double-sided.
62+
Default is `True`.
63+
64+
Returns
65+
-------
66+
tuple
67+
(freq, psd)
68+
Tuple containing frequency array and PSD of input data.
69+
"""
3370
(freq_ss, psd_ss, freq_ds, psd_ds) = calc_psd(np.array(data), fs=fs, nfft=nfft)
3471
if single_sided:
3572
return (freq_ss, psd_ss * fs / nfft)
3673
return (freq_ds, psd_ds * fs / nfft)
3774

3875

3976
def window_data(data, window="rectangular"):
40-
"""Applies a window to the time-domain data."""
77+
"""
78+
Applies a window to the time-domain data.
79+
80+
Parameters
81+
----------
82+
data : ndarray
83+
Time-series input data.
84+
window : str, optional
85+
Window to use for input data. Default is rectangular.
86+
87+
Returns
88+
-------
89+
ndarray
90+
Windowed version of input data.
91+
"""
4192
try:
4293
wsize = data.size
4394
except AttributeError:
@@ -71,7 +122,41 @@ def plot_spectrum(
71122
single_sided=True,
72123
fscale=("MHz", 1e6),
73124
):
74-
"""Plot Power Spectrum for input signal."""
125+
"""
126+
Plot Power Spectrum for input signal.
127+
128+
Parameters
129+
----------
130+
data : ndarray
131+
Time-series input data.
132+
fs : float, optional
133+
Sample frequency of the input time series data in Hz. Default is 1Hz.
134+
nfft : int, optional
135+
Number of FFT samples to use for PSD calculation. Default is 2^12.
136+
dr : float, optional
137+
Dynamic range for input data to be referenced to. Default is 1.
138+
harmonics : int, optional
139+
Number of harmonics to calculate and annotate on plot. Default is 7.
140+
leak : int, optional
141+
Number of leakage bins to use in signal and harmonic calculation. Default is 1.
142+
window : str, optional
143+
Type of input window to use for input data. Default is rectangular.
144+
no_plot : bool, optional
145+
Selects whether to plot (`False`) or not (`True`). Default is `False`.
146+
yaxis : str, optional
147+
Selects y-axis reference units. Example: `power`, `fullscale`, etc. Default is `power`.
148+
single_sided : bool, optional
149+
Set to `True` for single-sided spectrum or `False` for double-sided.
150+
Default is `True`.
151+
fscale : tuple, optional
152+
Selects x-axis scaling and units. Default is ('MHz', 1e6).
153+
154+
Returns
155+
-------
156+
tuple
157+
(freq, psd, stats)
158+
Tuple containing frequency array, PSD of input data, and calculated statstics dictionary.
159+
"""
75160
(freq, pwr) = get_spectrum(data, fs=fs, nfft=nfft, single_sided=single_sided)
76161

77162
# Calculate the fullscale range of the spectrum in Watts
@@ -210,7 +295,41 @@ def analyze(
210295
single_sided=True,
211296
fscale="MHz",
212297
):
213-
"""Perform spectral analysis on input waveform."""
298+
"""
299+
Perform spectral analysis on input waveform.
300+
301+
Parameters
302+
----------
303+
data : ndarray
304+
Time-series input data.
305+
nfft : int
306+
Number of FFT samples to use for PSD calculation.
307+
fs : float, optional
308+
Sample frequency of the input time series data in Hz. Default is 1Hz.
309+
dr : float, optional
310+
Dynamic range for input data to be referenced to. Default is 1.
311+
harmonics : int, optional
312+
Number of harmonics to calculate and annotate on plot. Default is 7.
313+
leak : int, optional
314+
Number of leakage bins to use in signal and harmonic calculation. Default is 1.
315+
window : str, optional
316+
Type of input window to use for input data. Default is rectangular.
317+
no_plot : bool, optional
318+
Selects whether to plot (`False`) or not (`True`). Default is `False`.
319+
yaxis : str, optional
320+
Selects y-axis reference units. Example: `power`, `fullscale`, etc. Default is `power`.
321+
single_sided : bool, optional
322+
Set to `True` for single-sided spectrum or `False` for double-sided.
323+
Default is `True`.
324+
fscale : str, optional
325+
Selects x-axis units. Default is 'MHz'.
326+
327+
Returns
328+
-------
329+
tuple
330+
(freq, psd, stats)
331+
Tuple containing frequency array, PSD of input data, and calculated statstics dictionary.
332+
"""
214333
fscalar = {
215334
"uHz": 1e-6,
216335
"mHz": 1e-3,

‎adc_eval/filt.py‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,6 @@ class CICDecimate:
1212
"""
1313
Generic CIC Decimator Object.
1414
15-
...
16-
1715
Parameters
1816
----------
1917
dec : int, default=2
@@ -138,8 +136,6 @@ class FIRLowPass:
138136
"""
139137
Generic FIR Low Pass Filter.
140138
141-
...
142-
143139
Parameters
144140
----------
145141
dec : int, optional

0 commit comments

Comments
 (0)