v1.1.0

New features

• Enabled adding KymoTrackGroup instances with tracks from different source kymographs. Note that certain features (e.g., KymoTrackGroup.ensemble_msd() and KymoTrackGroup.ensemble_diffusion("ols")) require that all source kymographs have the same pixel size and scan line times. See the kymotracking tutorial for more information.
• Added DwelltimeModel.profile_likelihood() for calculating profile likelihoods for dwell time analysis. These can be used to determine confidence intervals and assess whether the model has too many parameters (i.e., if a model with fewer components would be sufficient). See the population dynamics tutorial for more information.
• Added functionality to split tracks in the Kymotracking widget.
• Added functionality to provide minimum and maximum observation times per data point to DwelltimeModel and DwelltimeBootstrap.

Bug fixes

• Fixed a bug that would round the center of the window to the incorrect pixel when using KymoTrack.sample_from_image(). Pixels are defined with their origin at the center of the pixel, whereas this function incorrectly assumed that the origin was on the edge of the pixel. The effects of this bug are larger for small windows. For backward compatibility this bugfix is not enabled by default. To enable the bugfix specify correct_origin=True as a keyword argument to the method.
• Fixed bug that could lead to mutability of Kymo and Scan through .get_image() or .timestamps. This bug was introduced in 0.7.2. Grabbing a single color image from a Scan or Kymo using .get_image() returns a reference to an internal image cache. This numpy array was write-able and modifying data in the returned image would result in future calls to .get_image() returning the modified data rather than the original Kymo or Scan image. Timestamps obtained from .timestamps were similarly affected. These arrays are now returned non-writeable.
• Fixed a bug where we passed a SampleFormat tag while saving to tiff using tifffile. However, tifffile infers the SampleFormat automatically from the datatype of the numpy array it is passed. This produced warnings on the latest version of tifffile when running the benchmark.
• Ensure that the probability density returns zero outside its support for DwelltimeModel.pdf(). Prior to this change, non-zero values would be returned outside the observation limits of the dwelltime model.
• Fixed a bug where DwelltimeModel.hist() produces one less bin than requested with n_bins.
• Fixed a bug where lk.dsdna_ewlc_odijk_distance() erroneously returned a model where force is the dependent variable rather than distance. This bug was introduced in 0.13.2. Note that lk.ewlc_odijk_distance() was unaffected. It was specifically the convenience function with DNA parameters that was affected.

Improvements

• Improve API description of the channel data in a default FdCurve.
• Improved fitting performance dwell time analyses by implementing analytic gradient.
• Added lower and upper bounds when fitting dwell time models. This prevents numerical issues that occur when approaching these extremes. Prior to this change, over-parameterized models could encounter numerical issues due to divisions by (near) zero. After this change, amplitudes are constrained to stay between 1e-9 and 1.0 - 1e-9, while lifetimes are constrained to remain between 1e-8 and 1e8.
• Provided better initial guess for dwell time models with three or more components. Prior to this change, the dwelltime models involving three components or more would get an initial guess with an average lifetime beyond the mean of the observations.
• Silenced false positive warnings about the optimization violating the bound constraints. Prior to this change, dwell time analysis would produce warnings about the optimizer exceeding bounds. These excursions beyond the bound are very small and have no effect on the model.
• Parameters corresponding to Gaussian refinement are now preserved when two refined tracks are concatenated.
• Set the minimum value for the Min length slider in the Kymotracking widget to 2.

v1.0.0

New features

• Added links to example data for all tutorials. Try running them in a jupyter notebook!
• Added API to create a Kymo from an ImageStack. See ImageStack.to_kymo() for more information.
• Added API for accessing notes in a h5 file, i.e. file.notes returns a dictionary of notes.
• Implemented bias correction for centroid refinement that shrinks the window to reduce estimation bias. This bias correction can be toggled by passing a bias_correction argument to lk.track_greedy() and lk.refine_tracks_centroid(). Note that this bias correction is enabled by default.
• Implemented spatial calibration for ImageStack. Images are now plotted in units of microns for TIF files which contain pixel size in the metadata. If the metadata is unavailable, the axes units are provided in pixels.
• Added option to show scale bars to image plots using lk.ScaleBar(). See plotting and exporting for an example.
• Added KymoTrackGroup.remove() to remove a KymoTrack from a KymoTrackGroup.
• Enabled boolean array indexing (e.g. tracks[[False, False, True]]) and indexing with arrays of indices (e.g. tracks[[1, 3]]) for KymoTrackGroup. See the API documentation for more information.
• Improved force calibration documentation. See the new Tutorial and Theory section.
• Added API to look up (pixel)size of an ImageStack. See ImageStack for more information.
• Enabled forwarding plot style arguments to Slice.range_selector(). Prior to this change, a plot with markers was always opened which resulted in very poor performance when plotting high frequency data.

Breaking changes

• Pylake now requires Python version >= v3.9 and matplotlib version >= v3.5
• When performing particle tracking on kymographs, bias correction is now enabled by default; without this correction, kymographs with high background signal will suffer from biased localization estimates. To disable bias correction, specify bias_correction=False to lk.track_greedy() and lk.refine_tracks_centroid().
• The function ImageStack.define_tether() now takes coordinates in calibrated spatial units (microns) rather than pixels. If calibration to microns is not available, units are still in pixels.
• Optional arguments for lk.track_greedy() and lk.track_lines() are now enforced as keyword only.
• The vel argument has been renamed to velocity for lk.track_greedy().
• lk.track_lines() now performs bias-corrected centroid refinement after tracking to improve localization accuracy. Note that the old behaviour can be recovered by passing refine=False.
• When removing tracks with the kymotracking widget, only tracks that are entirely in the selection rectangle will be removed. Prior to this change, any tracks intersecting with the selection rectangle would be removed.
• Added checks which enforce KymoTracks in a KymoTrackGroup to be unique. Extending a KymoTrackGroup with KymoTrack instances that are already part of the group will now result in a ValueError. Similarly, constructing a new KymoTrackGroup with duplicate KymoTracks will also produce a ValueError.
• Removed all deprecated methods and properties from Kymo, Scan, PointScan, and ImageStack.
• Removed deprecated methods KymoTrack.estimate_diffusion_ols() and KymoTrackGroup.remove_lines_in_rect()
• Removed deprecated functions filter_lines(), refine_lines_centroid() and refine_lines_gaussian().
• Removed deprecated property lines and method save_lines from KymoWidgetGreedy.
• Removed deprecated argument exclude from Kymo.line_timestamp_ranges() and Scan.frame_timestamp_ranges(). Use the argument include_dead_time instead.
• Removed deprecated argument line_width from lk.track_greedy().
• Changed several asserts to Exceptions.
  • Attempting to read a KymoTrackGroup from a CSV file that doesn't have the expected file format will result in an IOError.
  • Attempting to extend a KymoTrackGroup by a KymoTrackGroup tracked on a different Kymo now results in a ValueError.
  • Attempting to connect two tracks with the same start and ending time point now raises a ValueError.
  • FdFitter: FdFit.fit() now raises a RuntimeError when a fit has no data or fittable parameters.
  • FdFitter: FdFit.plot() now raises a KeyError when trying to plot data that does not exist.
  • FdFitter: FdFit.plot() now raises a RuntimeError when trying to plot a fit with multiple models without selecting a model using angular brackets [] first.
  • FdFitter: FdFit.profile_likelihood() now raises a ValueError when max_step <= min_step or max_chi2_step <= min_chi2_step.
  • FdFitter: when inverting a model with interpolate=True, Pylake now raises a ValueError if the minimum or maximum is not finite.
  • FdFitter: a ValueError is raised when adding incompatible models.
  • FdFitter: When adding data to a fit, adding data with an unequal number of points for the dependent and indep...

v0.13.3

New features

• Added KymoTrackGroup.ensemble_diffusion() for estimating an average diffusion constant for a collection of tracks.
• Added diffusion theory section which details methods used for quantifying diffusive motion. Note that this documentation can be downloaded and run inside a Jupyter notebook.
• Added KymoTrack.plot() and KymoTrackGroup.plot() methods to conveniently plot the coordinates of tracked lines. See the kymotracking documentation for more details.
• Added the lk.GaussianMixtureModel.extract_dwell_times() method to calculate dwell-times for all states from channel data.
• Added lk.colormaps with custom colormaps for plotting single-channel images. Note: this is a namedtuple so you can access the attributes using the dot notation (for example kymo.plot("blue", cmap=lk.colormaps.cyan)). The available attributes are red, green, blue, magenta, yellow, cyan.
• Added localization_variance to DiffusionEstimate. This quantity is useful for determining the diffusive SNR.
• Added variance_of_localization_variance to DiffusionEstimate when calculating an ensemble CVE. This provides an estimate of the variance of the averaged localization uncertainty.
• Added option to pass a localization variance and its uncertainty to KymoTrack.estimate_diffusion().
• Added option to calculate a diffusion estimate based on the ensemble MSDs using the Ordinary Least Squares (OLS) method.
• Added DwelltimeBootstrap.extend() to draw additional samples for the distribution.

Bug fixes

• Fixed a bug that resulted in an incorrect round-off of the window size to pixels when kymotracking. This bug resulted in using one more pixel on each side than intended for specific track_widths. Track width is selected by rounding to the next odd window size. Prior to this change, the number of points used would increase on even window sizes. As a result, requesting a track width of 2.5 pixels, would result in using a window of size 5. Currently, requested a track width of 3 pixels results in a window of size 3, while 3.1 rounds up to the next odd window size (5). This bug affected the kymo tracking widget (tracking, refinement and photon count sampling during saving), lk.track_greedy() and lk.refine_tracks_centroid().
• Updated default slider ranges for the Kymotracker widget to reflect minimum track width required for tracking.
• Fixed issue with model description not being available in Jupyter notebooks for some force-distance models.
• Show validity criterion for Marko Siggia WLC models in terms of model parameters. Prior to this change the limit was simply denoted as 10 pN where in reality it depends on the model parameters. The 10 pN was a reasonable value for most DNA constructs.
• Fixed bug which occurred when exporting images to TIFF files of a numerical type with insufficient range for the data with the flag clip=True. Prior to this change, values exceeding the range of the numerical type were not clearly defined. After this change values below and above the supported range are clipped to the lowest or highest value of the data type respectively.
• Fixed bug in DwelltimeBootstrap.hist() (previously named DwelltimeBootstrap.plot(), see below). Previously, only up to two components were plotted; now all components are plotted appropriately.
• DwelltimeBootstrap.hist() now displays the original parameter estimate rather than the mean of the bootstrap distribution; the bootstrap distribution is used solely to calculate the confidence intervals via DwelltimeBootstrap.get_interval().
• Fixed a bug where Scan.export_video() and ImageStack.export_video() would show elements from a previous plot.
• Fixed a bug that caused a misalignment of half a pixel between the kymograph and its position histogram when using Kymo.plot_with_position_histogram().

Deprecations

• Renamed CorrelatedStack to ImageStack.
• Deprecated the DwelltimeModel.bootstrap attribute; this attribute will be removed in a future release. Instead, DwelltimeModel.calculate_bootstrap() now returns a DwelltimeBootstrap instance directly. See the population dynamics documentation for more details.
• Deprecated DwelltimeBootstrap.plot() and renamed to DwelltimeBootstrap.hist() to more closely match the figure that is generated.
• Deprecated DwelltimeBootstrap.calculate_stats(). This method is replaced with DwelltimeBootstrap.get_interval() which returns the 100*(1-alpha) % confidence interval; unlike DwelltimeBootstrap.calculate_stats(), it does not return the mean.

Other changes

• DwelltimeBootstrap is now a frozen dataclass.
• Attempting to access DwelltimeModel.bootstrap before sampling now raises a RuntimeError; however, see the deprecation note above for proper API to access bootstrapping distributions.
• Suppress legend entry for outline when invoking KymoTrack.plot().
• Allow pickling force calibration results (CalibrationResults). Prior to this change two functions involved in calculating upper parameter bounds prevented this class from being pickled.

v0.13.2

New features

• Added covariance-based estimator (cve) option to KymoTrack.estimate_diffusion(). See kymotracker documentation for more details.
• TIFFs exported from Scan and Kymo now contain metadata. The DateTime tag indicates the start/stop timestamp of each frame. The ImageDescription tag contains additional information about the confocal acquisition parameters.
• Added the Kymo.duration property to provide convenient access to the total scan time in seconds.
• Added addition operator to KymoTrackGroup. KymoTrackGroups tracked on the same Kymo can be concatenated with the + operator.
• Added the optional min_length parameter to KymoTrackGroup.estimate_diffusion() to discard tracks shorter than a specified length from the analysis.
• Added the DwelltimeModel.rate_constants property along with additional documentation explaining the assumptions that underlie using the exponential model. See the dwell time analysis documentation for more information.
• Ensure same call signature for plot() methods for Scan, Kymo, PointScan and CorrelatedStack:
  • Scan, Kymo and PointScan: Made argument channel optional.
  • Scan and PointScan: Added argument show_title.
  • Kymo: Added arguments image_handle and show_title.
  • CorrelatedStack: See deprecation changelog entry.
• Introduced lazy loading for TimeSeries data. This means that the data corresponding to a TimeSeries channel is not read from disk until it is used.

Bugfixes

• Added a check which verifies that a Kymo is not downsampled prior to estimating a diffusion constant. Computing diffusion constants from temporally downsampled kymographs is now explicitly disallowed.
• Fixed a bug in KymoTrack.estimate_diffusion() that could lead to biased estimates obtained with the "ols" estimator. For the diffusion estimate itself to be affected, specific lags have to be missing from the track (for example every second point in a track). This is a regression that was introduced in v0.12.1.
• Added a warning to KymoTrack.estimate_diffusion() used with the "ols" method when points are missing from a track. In this case the uncertainty estimate is biased. See the section on diffusive processes for more details.
• Added a warning that estimating the optimal number of points to use when using the "ols" method can be biased if many points are missing.
• Fixed a bug in KymoTrack.estimate_diffusion() that could lead to biased estimates obtained with the "gls" estimator when gaps occur in the track. Such cases now produce an exception recommending the user to refine the track prior to diffusion estimation. See the section on diffusive processes for more details.
• Fixed issue where on Jupyter Lab the kymotracker widget would align the Kymograph and track parameters vertically rather than horizontally.
• Functions that use KymoTrackGroup now gracefully handle the cases where no tracks are available. The refinement functions refine_tracks_centroid() and refine_tracks_gaussian() return an empty list, while KymoTrackGroup.fit_binding_times() and KymoTrackGroup.plot_binding_histogram() raise an exception.
• lk.track_greedy() now returns an empty KymoTrackGroup instead of an empty list when no coordinates exceed the threshold.
• lk.track_greedy() now returns an empty KymoTrackGroup instead of an error when an ROI is selected that results in no lines tracked.
• Fixed a bug where the pixel_threshold could be set to zero for an empty image. Now the minimum pixel_threshold is one.
• Fixed a bug where single pixel detections in a KymoTrackGroup would contribute values with a dwell time of zero. These are now dropped, the correct minimally observable time is set appropriately and a warning is issued.
• Fixed slicing of a Kymo where slicing from a time point inside the last line to the end (e.g. kymo["5s":]) resulted in a Kymo which returned errors upon trying to access its contents.
• Fixed a minor bug in force calibration. In rare cases it was possible that the procedure to generate an initial guess for the power spectral fit failed. This seemed to occur when the spectrum supplied is a mostly flat plateau. After the fix, an alternative method to compute an initial guess is applied in cases where the regular method fails. Note that successful calibrations were not at risk for being incorrect due to this bug since they would have resulted in an exception rather than an invalid result.

Deprecations

• Deprecated property CorrelatedStack.src. In future versions, the contents of src will be considered an implementation detail that is not directly accessible. Data should be accessed through the public API.
• Reordered the keyword arguments of the method CorrelatedStack.plot() and enforced all parameters after channel to be keyword arguments. For details see the docstring.
• Enforced the argument axes of the method plot() for Scan, Kymo and PointScan to be a keyword argument.
• Renamed force distance fitting functions. They are deprecated now and will be removed in the future:
  • inverted_marko_siggia_simplified -> wlc_marko_siggia_distance
  • marko_siggia_simplified -> wlc_marko_siggia_force
  • marko_siggia_ewlc_distance -> ewlc_marko_siggia_distance
  • marko_siggia_ewlc_force -> ewlc_marko_siggia_force
  • odijk -> ewlc_odijk_distance
  • inverted_odijk -> ewlc_odijk_force
  • freely_jointed_chain -> efjc_distance
  • inverted_freely_jointed_chain -> efjc_force
  • twistable_wlc -> twlc_distance
  • inverted_twistable_wlc -> twlc_force

Other changes

• All KymoTrack instances must have the same source Kymo and color channel in order to be in the same KymoTrackGroup instance. While this behavior was required previously for some downstream analyses on the tracks, it is now explicitly enforced upon KymoTrackGroup construction.
• When calling KymoTrackGroup.estimate_diffusion() without specifying the min_length parameter, tracks which are shorter than the required length for the specified method will be discarded from analysis and a warning emitted. Previously, if any tracks were shorter than required, an error would be raised.
• Updated benchmark to not use deprecated functions and arguments. Prior to this change, running the benchmark would produce deprecation warnings.
• Kymo.plot() now returns a handle of the plotted image.
• PointScan.plot() now returns a list of handles of the plotted lines.

v0.13.1

Bug fixes

• Reverted lazy loading for TimeSeries data as this actually caused significantly long wait times for accessing the data.

v0.13.0

New features

• Added possibility to access property sample_rate for TimeSeries data with constant sample rate.
• Allow reading multiple files with lk.CorrelatedStack (e.g. lk.CorrelatedStack("image1.tiff", "image2.tiff")).
• Added CorrelatedStack.export_video() to export videos to export multi-frame videos to video formats or GIFs.
• Added support for steps when slicing frames from CorrelatedStacks.
• Added function Kymo.line_timestamp_ranges() to obtain the start and stop timestamp of each scan line in a Kymo. Please refer to Confocal images for more information.
• Added Kymo.flip() to flip a Kymograph along its positional axis.
• Added KymoTrackGroup.estimate_diffusion() to estimate diffusion constants for a group of kymograph traces.
• Include unit in DiffusionEstimate dataclass.
• Added shape property to Scan and Kymo.
• Allow slicing CorrelatedStacks with timestamps and time strings (e.g. stack["5s":"10s"] or stack[f.force1x.start:f.force1x.stop]).
• Allow slicing Scan with timestamps and time strings (e.g. scan["5s":"10s"] or scan[f.force1x.start:f.force1x.stop]).
• Allow downloading files directly from Zenodo using lk.download_from_doi(). See the example on Cas9 binding for an example of its use.
• Made piezo tracking functionality public and added piezo tracking tutorial.
• Lazily load data and timestamps for TimeSeries data
• Propagate Slice axis labels when performing arithmetic (when possible).
• Added a warning to the Kymotracker widget if the threshold parameter is set too low, which may result in slow tracking and the widget hanging.
• Added header line to exported track coordinate CSV files. The first header line now contains the version of Pylake which generated the file and a version number for the CSV file itself (starting with v2 from this release).
• It is now possible to pickle FdFit objects. Prior to this change, unpickling an FdFit would fail since model identification relied on a stored id for each of the models used. The id of a variable changes whenever a new variable is created however. After this change, each model is associated with a universally unique identifier (uuid) that is used for identification instead. This uuid is serialized with the Model and used by FdFit thereby preserving their relationship when pickled/unpickled.

Bug fixes

• Improved scan.get_image("rgb") to handle missing channel data. Missing channels are now handled gracefully. Missing channels are zero filled matching the dimensions of the remaining channels.
• Added calls to manually redraw the axes in the kymotracker widget during horizontal pan and line connection callbacks. Without this, the plot did not update correctly when using newer versions of ipywidgets and matplotlib.
• Fixed a bug in the video export that led to one frame less being exported than intended.
• Fixed a bug which prevented the range selector widget from updating when the dataset to be plotted is changed. Previously, on some supported versions of matplotlib it would no longer update the figure. This is now fixed.
• Force distance models now raise a ValueError exception when simulated for invalid parameter values.
• Force distance models now have a non-zero lower bound for the contour length (Lc), persistence length (Lp), stretch modulus (St) and Boltzmann constant times temperature (kT) instead of a lower bound of zero.
• Force distance fits now raise a RuntimeError if any of the returned simulation values are NaN.
• Fixed a bug that resulted in profile likelihood automatically failing when an attempted step exceeded the bounds where the model could be simulated.

Breaking changes

• To disable image alignment for lk.CorrelatedStack, the alignment argument has to be provided as a keyword argument (e.g. lk.CorrelatedStack("filename.tiff", align=False) rather than lk.CorrelatedStack("filename.tiff", False)).
• Removed deprecated argument roi from CorrelatedStack.export_tiff. Use CorrelatedStack.crop_by_pixels() to select the ROI before exporting.
• CorrelatedStack.frame_timestamp_ranges() is now a method rather than a property. This was done for API consistency with the API for Scan. Please refer to Correlated stacks for more information.
• Removed public attributes CorrelatedStack.start_idx and CorrelatedStack.stop_idx and made them protected.
• The property sample_rate of Continuous data now returns a float instead of an int.
• Changed the error type when attempting to access undefined per-pixel timestamps in Kymo from AttributeError to NotImplementedError.
• KymoWidgetGreedy now enforces using keywords for all arguments after the first two (kymo and channel).
• The following KymoWidgetGreedy attributes/functions have been removed (replaced with private API): adding, algorithm_parameters, axis_aspect_ratio, output_filename, plotted_lines, show_lines, create_algorithm_sliders(), refine(), show(), track_all(), track_kymo() and update_lines().
• The track_width argument of refine_tracks_centroid() expects values in physical units whereas the deprecated refine_lines_centroid() expected the line_width argument in pixel units.
• Removed default value provided for driving_frequency_guess in lk.calibrate_force().
• It is now mandatory to supply a sample_rate when calling lk.calibrate_force().
• It is now mandatory to supply a sample_rate when calling lumicks.pylake.force_calibration.touchdown.touchdown().

Deprecations

• Scan.save_tiff() and Kymo.save_tiff() were deprecated and replaced with Scan.export_tiff() and Kymo.export_tiff() to more clearly communicate that the data is exported to a different format.
• Deprecated export_video_red(), export_video_green(), export_video_blue(), and export_video_rgb() methods for Scan. These methods have been replaced with a single export_video(channel=color) method.
• In the functions Scan.frame_timestamp_ranges() and Kymo.line_timestamp_ranges(), the parameter exclude was deprecated in favor of include_dead_time for clarity.
• Deprecated KymoTrackGroup.remove_lines_in_rect(); use KymoTrackGroup.remove_tracks_in_rect() instead (see below).
• Deprecated the line_width argument of track_greedy(); use track_width instead.
• Deprecated filter_lines(); use filter_tracks() instead.
• Deprecated refine_lines_centroid(); use refine_tracks_centroid() instead. Note: the track_width argument of refine_tracks_centroid() expects values in physical units whereas the previous refine_lines_centroid() expected the line_width argument in pixel units.
• Deprecated refine_lines_gaussian(); use refine_tracks_gaussian() instead.
• Deprecated KymoWidget.save_lines(); use KymoWidget.save_tracks() instead.

Other changes

• Added default values for the track_greedy() arguments track_width and pixel_threshold.
• Renamed classes/methods/functions dealing with tracked particles. This change was made to avoid ambiguity with regard to the term "line". Now, a "line" refers to a single scan pass of the confocal mirror during imaging. A "track" refers to the coordinates of tracked particles from a kymograph. Note: Any breaking changes or deprecations to the public API are noted above. The renamed classes/functions below are considered internal API and subject to change without notice; these classes should not be constructed manually:
  • KymoLine was renamed to KymoTrack
  • KymoLineGroup was renamed to KymoTrackGroup
  • export_kymolinegroup_to_csv() was renamed to export_kymotrackgroup_to_csv()
  • import_kymolinegroup_from_csv() was renamed to import_kymotrackgroup_from_csv()
• Updated the KymoWidgetGreedy UI to reflect changes in terminology.
• Made ipywidgets>=7.0.0 and notebook>=4.4.1 optional dependencies for pip.
• Made notebook>=4.4.1 a mandatory dependency for conda release.
• Pylake now depends on h5py>=3.4, <4. This change is required to support lazy loading for TimeSeries.

v0.12.1

New features

• Added Scan.pixel_time_seconds and Kymo.pixel_time_seconds to obtain the pixel dwell time. See Confocal images for more information.
• Allow cropping CorrelatedStack using multidimensional indexing, i.e. stack[start_frame : end_frame, start_row : end_row, start_column : end_column]. See Correlated stacks for more information.
• Added KymoLine.estimate_diffusion() which provides additional information regarding the diffusion constant estimation. This dataclass can be converted to floating point to get just the estimate, but also contains the number of points used to compute the estimate, and the number of lags used in the analysis. In addition to that, it provides a std_err field which reports the standard error for the estimate.
• Added generalized least squares method as method option for KymoLine.estimate_diffusion(). Please refer to the kymotracker documentation for more information.
• Added offline piezo tracking functionality (documentation pending).
• Added lk.benchmark() that can be used to estimate the performance of your computer with various pylake tasks.

Bug fixes

• Changed the internal calculation of the extent argument in Kymo.plot() such that the spatial limits are now defined at the center of the pixel (same functionality that is used for the temporal axis). Previously the limits were defined at the edge of the pixel resulting in a subtle misalignment between the coordinates of the tracked lines and the actual image.
• Fixed an issue where the pixel dwell time stored in TIFFs exported from Pylake could be incorrect. Prior to this fix, Pylake exported the value entered in the Bluelake UI as pixel dwell time. In reality, the true pixel dwell time is a multiple of the acquisition sample rate. After the fix, TIFF files correctly report the achieved pixel dwell time.
• Changed the internal calculation of the hydrodynamically correct force spectrum. Before this change, the computation of the power spectral density relied on the frequencies always being positive. While this change does not affect any results, it allows evaluating the power spectral density for negative frequencies.
• Fixed an issue where evaluating the hydrodynamically correct spectrum up to very high frequencies could lead to precision losses. These precision losses typically occur at frequencies upwards of 30 kHz and manifest themselves as visible discontinuities.
• Perform better input validation on the kymotracking functions track_greedy and track_lines. The line width and pixel threshold must be larger than zero. The diffusion parameter must be positive. Previously, failure to provide values respecting these limits would produce cryptic error messages.
• Perform better input validation on refine_lines_centroid. Line width must now be at least one pixel. Previously, negative values produced a cryptic error message, while a line width smaller than one pixel would silently result in no refinement taking place.
• Fixed bug in force calibration convenience function where setting fixed_alpha or fixed_diode to zero resulted in those parameters still being fitted. After this change, setting fixed_alpha to zero will result in the diode model having a fixed alpha of zero, whereas setting f_diode to zero raises an exception.
• Include one extra sample when requesting frame timestamp ranges from a scan (Scan.frame_timestamp_ranges(exclude=True)). Previously, when slicing using these timestamps, you would omit the last sample of the scan. Now this sample will be included.

Deprecations

• KymoLine.estimate_diffusion_ols() is now deprecated; use KymoLine.estimate_diffusion(method="ols") instead. This new method returns the same estimate of the diffusion coefficient as before but includes additional information about the fit.

v0.12.0

New features

• Support negating channels (e.g. neg_force = - file.force1x). See files and channels for more information.
• Allow applying color intensity adjustments on images using lk.ColorAdjustment(). See Confocal images and Correlated stacks for more information.
• Added DwelltimeModel to fit dwelltimes to an exponential (mixture) distribution. For more information, see the tutorials section on Population Dynamics
• Allow slicing directly with an object with a .start and .stop property. See files and channels for more information.
• Allow boolean array indexing on Slice (e.g. file.force1x[file.force1x.data > 5]. See files and channels for more information.
• When performing arithmetic on Slice, the calibration is propagated if it is still valid.
• Allow applying a gamma adjustment on images using lk.ColorAdjustment(). See Confocal images and Correlated stacks for more information.
• Added lk.dsdna_odijk() and lk.ssdna_fjc() convenience functions to build Fd models for dsDNA and ssDNA with parameter defaults based on literature.

Bug fixes

• Fixed a minor bug in KymoLineGroup.fit_binding_times(). Previously, the binding time for all lines in the group were used for the analysis. However, lines which start in the first frame of the kymo or end in the last frame have ambiguous dwelltimes as the start or end of the line is not known definitively. Now, the default behavior is to exclude these lines from the analysis. This behavior can be overridden with the keyword argument exclude_ambiguous_dwells=False. In general, this bug would lead to only very minor biases in the results unless the number of dwells to be excluded is large relative to the total number.
• Fixed bug in vmax handling for CorrelatedStack. Before vmax values were scaled to the maximally possible range of values for the image instead of the actual intensity value. Note that use of vmax and vmin is deprecated and one should use adjustment=lk.ColorAdjustment(min, max) for color adjustments. See Correlated stacks for more information.
• Fixed a bug in the kymotracker in which the plotted aspect ratio did not match the requested axis_aspect_ratio argument.

Deprecations

• Deprecated red_image, green_image, blue_image, and rgb_image properties for Scan and Kymo. These data should now be accessed using the get_image(channel="{color}") method (where "{color}" can be "red", "green", "blue", or "rgb").

Breaking changes

• Changed the frame indexing convention for plotting confocal scans to match CorrelatedStack.plot(). Previously, Scan.plot(frame=1) referred to the first frame in the stack. Now, indexing starts at 0.
• Requesting a frame outside of the available range for Scan.plot() now throws an IndexError.
• Removed deprecated properties scan_width_um, json, has_force, has_fluorescence from confocal classes.

Other changes

• Changed titles for all plots of Scan and CorrelatedStack images to be consistent. First frame is titled as "[frame 1 / N]" and last frame is titled as "[frame N / N]".
• The returned type from KymoLineGroup.fit_binding_times() has been changed to DwelltimeModel. Note, this class has the same public attributes and methods as the previously returned BindingDwelltimes class; however the plot() method has been deprecated and renamed to DwelltimeModel.hist(). This new method name more closely describes the actual functionality and also unifies the API with GaussianMixtureModel.
• KymoLine is now immutable.
• Removed examples directory. Application examples can be found in the online documentation.

v0.11.1

New features

• Added support for Python 3.10.
• Added CorrelatedStack.define_tether() which can be used to define the endpoints of the tether between two beads and return image data rotated such that the tether is horizontal. Check out the documentation for more information.
• Added function to correlate Scan frames to channel data. See Confocal images.
• Added CorrelatedStack.crop_and_rotate() for interactive editing of the image stack. Actions include scrolling through image frames with the mouse wheel, and left-clicking to define the tether coordinates, and right-click/drag to define a cropping region. Check out the documentation for more information.
• Added KymoLineGroup.plot_binding_histogram() to plot histograms of binding events for tracked lines. See Kymotracking for more details.
• Allow fixing the photon background parameter in refine_lines_gaussian(). See kymotracking for more information.
• Added option to specify a custom label when plotting fit with FdFit.plot(). See the tutorial section on Fd Fitting for more information.
• Added functionality to slice Scan objects by frame indices. See Confocal images.
• Added convenience function which allows users to perform a force calibration procedure with a single function call calibrate_force(). See force calibration.
• Added Kymo.crop_and_calibrate() for interactive cropping of a kymograph. If the optional tether_length_kbp argument is supplied, the resulting kymograph will be automatically calibrated to this length. Check out the documentation for more information.
• Added fallback to the function Kymo.plot_with_force() when only low-frequency force data is available.
• Added option to undo/redo actions in the kymotracker widget.
• Added option to fit peaks simultaneously in refine_lines_gaussian() using the flag overlap_strategy="fit_multiple". See kymotracking for more information.
• Added ability to manually connect two lines from any points (not just the ends) in the kymotracker widget.

Bug fixes

• Fixed issue which resulted in the offset parameter added by Model.subtract_independent_offset() not having a unit associated with it.
• Fixed bug which resulted in erroneous standard errors on parameter estimates computed from an FdFit with fixed parameters. For such a fitting problem, the covariance matrix was evaluated for the unconstrained problem (without the fixed parameter constraints). As a result, standard errors were always overestimated. Note that uncertainty estimation by profile likelihood was unaffected.
• Fixed issue which resulted in overly stringent positional tolerance when using the kymotracker widget. This tolerance has now been made proportional to the axis viewport.
• Removed axial parameter from lk.ActiveCalibrationModel() as we do not support active force calibration in the axial direction.
• Improved default scaling behaviour for CorrelatedStack.plot_correlated() and Scan.plot_correlated(). It now ensures the ratio between the image and temporal plot is according to the aspect ratio of the scan or stack.
• Slicing CorrelatedStack in reverse (i.e., stack[5:3]) or resulting in an empty stack (i.e., stack[5:5]) now throws an exception.
• Resolved DeprecationWarning for tifffile.imsave() and tifffile.TiffWriter.save() with tifffile >= 2020.9.30.
• Fixed a bug in refine_lines_gaussian() which incorrectly rounded the pixel position instead of flooring it. For pixels with a subpixel position larger than half the pixel, this resulted in shifting the window by one pixel in the positive direction. Typically, this would have little or no effect since the majority of the peak should still be covered.

Deprecations

• Deprecated CorrelatedStack.timestamps and replaced with CorrelatedStack.frame_timestamp_ranges. The reason for this change is that per-pixel timestamps are not defined for camera based images; therefore, this previous use was not in line with the use of the timestamps property of confocal image classes. This change also brings consistency with Scan.frame_timestamp_ranges.
• Deprecated plot_red(), plot_green(), plot_blue(), and plot_rgb() methods for PointScan, Scan, and Kymo. These methods have been replaced with a single .plot(channel={color}) method.

v0.11.0

New force calibration features

• Added support for active force calibration. For more information, please read: active force calibration.
• Added support for axial force calibration. See axial calibration for more information.
• Added support for using near-surface corrections for lateral and axial force calibration, please read: force calibration.
• Added function to compute viscosity of water at specific temperature. Please refer to: force calibration for more information.
• Added parameters describing the inferred driving peak (driving_amplitude, driving_frequency, driving_power) when performing active force calibration to CalibrationResults.

Other new features

• Added Kymo.calibrate_to_kbp() for calibrating the position axis of a kymograph from microns to kilobase-pairs. Note: this calibration is applied to the full kymograph, so one should crop to the bead edges with Kymo.crop_by_distance() before calling this method.
• Added CorrelatedStack.get_image() to get the image stack data as an np.ndarray.
• Allow setting custom slider ranges for the algorithm parameters in the kymotracker widget. Please refer to kymotracker widget for more information.
• Added function Scan.frame_timestamp_ranges() to obtain the start and stop timestamp of each frame in a Scan. Please refer to Confocal images for more information.

Bug fixes

• Fixed issue in force calibration where the analytical fit would sometimes fail when the corner frequency is below the lower fitting bound. What would happen is that the analytical fit resulted in a negative term of which the square root was taken to obtain the corner frequency. Now this case is gracefully handled by setting the initial guess halfway between the lowest frequency in the power spectrum and zero.
• Fixed issue that led to DeprecationWarning in the kymotracker widget.
• Fixed error in kymotracking documentation. The tutorial previously indicated the incorrect number of samples for sample_from_image.
• Fixed bug that would implicitly convert Kymograph and Scan timestamps to floating point values. Converting them to floating point values leads to a loss of precision. For more information see files and channels for more information.
• Fixed bug where color-aligned data was returned from TiffFrame.data although alignment was not requested (e.g., CorrelatedStack("filename.tiff", align=False)). This bug was introduced in v0.10.1.

Deprecations

• CorrelatedStack.raw has been deprecated and will be removed in a future release. Use CorrelatedStack.get_image() instead.

Breaking changes

• Changed default for viscosity in force calibration models. When omitted, pylake will use the viscosity of water calculated from the temperature. Note that this results in the default (when no viscosity or temperature is set) changing from 1.002e-3 to 1.00157e-3 Pa*s. Please refer to force calibration for more information.
• Units are now included in the headers for kymograph traces exported from the widget or with KymoLineGroup.save() (either um or kbp depending on the calibration of the kymograph). Any code that hardcoded the header names directly should be updated.
• Added more input validation for model parameters when performing force calibration. We now force bead and sample density to be more than 100 kg/m³ when specified. Temperature should be specified between 5 and 90 °C and viscosity should be bigger than 0.0003 Pa*s (viscosity of water at 90 degrees Celsius).