Extend seq.plot() for reuse ability. (1.4)

[mzaiss]

This PR makes seq.plot() more flexible for interactive use and debugging.

1. Added "clear=True" Parameter

The new clear flag defaulting to True ensures behavior as previously, which is that during repeated calls the plots in figure 1 and 2 get overwritten. Now, you can set clear=False to intentionally overlay sequences in the existing plots for direct comparison, which is useful for debugging subtle differences, but also great for educational purposes.

See here for two seqs with slightly different gradients (flat_area and flat_time vs. area and duration) and a corresponding shift in the rf pulse timing in this example.

2. Return Figure and Axes Objects

The function now returns its figure and axes objects (fig1, axes1, fig2, axes2), which allows for post-plot customization (e.g., adding titles, annotations, signal) or extracting axes.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
/home/runner/.local/lib/python3.12/site-packages/pypulseq
add_gradients.py	123	51	59%	44, 52, 58, 61, 75–86, 92, 120–123, 130–131, 150, 157, 162–241
add_ramps.py	36	36	0%	1–89
align.py	35	4	89%	41, 45, 69, 73
calc_duration.py	25	1	96%	37
calc_ramp.py	218	214	2%	45–353
calc_rf_bandwidth.py	27	20	26%	37–59, 63–67
check_timing.py	96	29	70%	78, 82, 107, 180, 199, 232, 239, 249–293
compress_shape.py	30	1	97%	28
convert.py	40	8	80%	42, 48, 66, 72–73, 82, 88–89
event_lib.py	96	14	85%	6–9, 48–51, 70–71, 205–210
make_adc.py	92	13	86%	63, 72–76, 79, 128, 131, 135, 141, 145, 184, 186, 188, 196
make_adiabatic_pulse.py	129	39	70%	196–200, 217–221, 229–230, 253, 259, 328–347, 451–460, 498–506
make_arbitrary_grad.py	37	7	81%	68, 71, 74, 77, 81, 83, 103
make_arbitrary_rf.py	66	55	17%	83–160
make_block_pulse.py	46	3	93%	112–116, 119
make_delay.py	9	1	89%	27
make_digital_output_pulse.py	16	2	88%	39, 47
make_extended_trapezoid.py	56	12	79%	67, 70, 76, 82, 85, 88, 91, 94, 116, 134, 136, 139
make_extended_trapezoid_area.py	93	3	97%	52, 227, 230
make_gauss_pulse.py	69	20	71%	127–131, 134–158, 165, 168
make_label.py	22	4	82%	64, 66, 68, 75
make_sigpy_pulse.py	116	31	73%	12–13, 112, 115, 119, 154, 157–161, 165, 168–169, 172–173, 188, 195, 200, 212, 215, 240–250, 264, 267, 297–307
make_sinc_pulse.py	68	10	85%	94, 100, 127–131, 135, 138–139, 142–143, 165
make_soft_delay.py	25	2	92%	102, 120
make_trapezoid.py	111	7	94%	177, 190, 196, 214, 232, 237, 255
make_trigger.py	16	2	88%	44, 52
opts.py	66	9	86%	78, 83, 102, 142, 166–170
points_to_waveform.py	9	1	89%	27
rotate.py	69	14	80%	15, 55, 66–69, 85–90, 112, 119–120
scale_grad.py	14	4	71%	28–30, 33
sigpy_pulse_opts.py	26	7	73%	34–41
split_gradient.py	39	31	21%	46–103
split_gradient_at.py	70	27	61%	63–90, 110, 114, 118–120, 154–156
traj_to_grad.py	13	9	31%	26–40
/home/runner/.local/lib/python3.12/site-packages/pypulseq/SAR
SAR_calc.py	113	98	13%	33–40, 55–62, 89–108, 129–132, 168–212, 242–246, 264–306
/home/runner/.local/lib/python3.12/site-packages/pypulseq/Sequence
block.py	405	37	91%	63, 66, 74, 80, 95, 103, 109, 120, 123, 126, 134, 139, 148, 159, 167, 207, 209, 213, 225, 274, 278, 294, 334–337, 366–367, 433, 439, 472, 541, 577, 583, 610, 648, 727
calc_grad_spectrum.py	81	76	6%	68–190
calc_pns.py	40	31	22%	45–96
ext_test_report.py	144	12	92%	23, 61, 138, 149–150, 237–243
install.py	75	42	44%	31, 52, 69, 71, 112–131, 148, 181–184, 200–212, 254–278
parula.py	4	2	50%	19–86
read_seq.py	319	68	79%	42–43, 90, 93, 105, 110, 116, 123, 132, 141, 146, 149, 157–159, 202, 207, 215–264, 294–297, 312–313, 342–359, 422, 425, 460, 468, 542, 584–588
sequence.py	815	226	72%	11–14, 104–114, 135–148, 195, 260–263, 310, 337, 354, 402, 430, 457–462, 499, 515, 606, 628, 669–672, 726, 764, 775–776, 782, 793, 799, 801, 809, 842–850, 994, 996, 999, 1017, 1026, 1042–1043, 1046–1049, 1085–1095, 1104–1106, 1150–1162, 1177–1178, 1194–1212, 1246–1247, 1276, 1282, 1285, 1288, 1325, 1446–1459, 1482, 1510, 1532–1534, 1555, 1618, 1626, 1693, 1704–1717, 1729–1740, 1786–1787, 1796–1814, 1838, 1868–1876, 1908–2018, 2054, 2068–2078, 2082, 2093
write_seq.py	354	176	50%	42, 66, 69–76, 303–526
/home/runner/.local/lib/python3.12/site-packages/pypulseq/utils
cumsum.py	14	1	93%	17
safe_pns_prediction.py	126	113	10%	50–87, 102–189, 197–214, 222, 244–250, 279–286, 310–336, 344–383, 396–411, 415
tracing.py	16	6	62%	33–34, 42, 54–55, 75
/home/runner/.local/lib/python3.12/site-packages/pypulseq/utils/siemens
asc_to_hw.py	58	53	9%	21–28, 48–106
readasc.py	48	45	6%	25–100
TOTAL	4719	1677	64%

Tests	Skipped	Failures	Errors	Time
1349	21 💤	0 ❌	0 🔥	3m 32s ⏱️

[mcencini]

Hi! I am not a maintainer, but just wanted to point out that v1.5.0_dev branch also has changes to plot.

[mzaiss]

Hi! I am not a maintainer, but just wanted to point out that v1.5.0_dev branch also has changes to plot.

i hope that the same reuse can be done there.
wil try to also make a PR

[schuenke]

I did some additional refactoring in 27e3fe1 to improve the general code style and documentation and to fix the issue that the grid was removed in every second function call when using the the clear=False option (grid was toggled, not explicitly swtiched on).

This PR changes the return value of the plot method from None to Tuple[plt.Figure, Tuple[plt.Axes, plt.Axes, plt.Axes], plt.Figure, Tuple[plt.Axes, plt.Axes, plt.Axes]]. IMO, this is not a problem, but something to keep in mind.

Would be great if @btasdelen and/or @FrankZijlstra and/or @mcencini could have a look at it again. I think it wouldn't be best practice if I approve this PR after all my modifications.

@mzaiss could you please confirm that everything is still working for you as expected after my changes