v1.5.2

Improvements

• Added a fallback which allows loading scans or kymographs that have truncated photon count channels.

Bug fixes

• Fixed bug that prevented opening the kymotracking widget when using it with the widget backend on matplotlib >= 3.9.0.
• Fixed bug where photon counts were not being loaded from a csv file generated with the kymotracker.

v1.4.1

Bug fixes

• Fixed statistical backing returning an incorrect value.
• Fixed bug that prevented loading an h5 file where only a subset of the photon channels are available. This bug was introduced in Pylake 1.4.0.

v1.5.1

• Fixed bug that prevented loading an h5 file where only a subset of the photon channels are available. This bug was introduced in Pylake 1.4.0.

v1.5.0

New features

• Support Python 3.12, dropped support for 3.9.
• Added Kymo.plot_with_channels() for plotting a kymograph with corresponding channel data. For more information, please refer to the kymograph tutorial.
• Added option to disable downsampling channel data to frame rates with correlated plots (ImageStack.plot_correlated(), Scan.plot_correlated()) and exported videos (ImageStack.export_video(), Scan.export_video()) using downsample_to_frames=False.
• Added err_kappa and err_Rd to force calibration results. These contain error estimates for the calibration constants propagated from the fitting errors.
• Added support for loading two-color TIF files with ImageStack.
• Made CalibrationResults callable to evaluate the fitted model power spectral density at the specified frequencies.
• Added fitted_params field to CalibrationResults for convenience.
• Allow accessing Model default parameters for a force-distance model by key (i.e. model["m/Lc"]).

Improvements

• Added error message when parameters are passed to lk.parameter_trace() that do not have the required attributes.
• Warn when parameter estimates are hitting the fitting bounds when using lk.parameter_trace().

Other changes

• Switch to notebook v7 with ipympl. Note that this means that you have to have to invoke %matplotlib widget in notebooks where you previously used %matplotlib notebook. See the jupyter notebook 7 announcement for more information.

Bug fixes

• Fixed statistical backing returning an incorrect value.
• Fixed bug where the start_frame parameter was being ignored when exporting a movie with ImageStack.export_video() and Scan.export_video(). This bug was introduced in Pylake v1.3.0.

v1.4.0

New features

• Added lk.HiddenMarkovModel for classifying data traces exhibiting transitions between discrete states. For more information, see the tutorials section on Population Dynamics.
• Added option to crop beads out of a kymograph using Kymo.crop_beads().
• Added API to determine bead edges in a kymograph using Kymo.estimate_bead_edges().
• Added emission_path() and plot_path() methods to lk.GaussianMixtureModel
• Added option to File to pass a custom mapping from Photon count detector to RGB colors colors. This is useful to reconstruct images on systems with non-standard imaging modules.
• Added option to customize the filter width of the Gaussian filter that is applied prior to spot detection in lk.track_greedy(). Increasing this value results in fewer false detections at the cost of resolution. Note that the current default is set to half a pixel to preserve the old behavior.
• Added option to determine the viscosity and density of water with NaCl dissolved in it using lk.viscosity_of_water() and lk.density_of_water().
• Added ImageStack.close() to force close file handles. Note that this prohibits further access to images from the ImageStack it is called on, but also any ImageStack derived from it (i.e. through ImageStack.define_tether() or ImageStack.crop_by_pixels()).
• Added option to filter kymograph spot detections where there are no detections in adjacent frames using adjacency_filter=True in lk.track_greedy().
• Add option to include_dead_time to ImageStack.plot_correlated() for Scan and ImageStack. This parameter defaults to True.

Bug fixes

• Fixed a bug where the time indicator was off by one frame in ImageStack.plot_correlated() and ImageStack.export_video().
• Fixed a bug where the time between frames was incorrectly not excluded when calling ImageStack.frame_timestamp_ranges() with include_dead_time=False. Note that Scan and Kymo are not affected.
• Fixed a bug where ImageStack.plot_correlated() was not excluding the dead time between frames.
• Fixed a bug where color adjustments on a single channel ImageStack would not be applied unless a channel was provided as argument. This bug was introduced in v1.3.0.
• Changed the DateTime tag on TIFFs exported with Pylake from Scan and Kymo objects. Before the change, the start and end of the scanning period in nanoseconds was stored. After the change, we store the starting timestamp of the frame, followed by the starting timestamp of the next frame to be consistent with data exported from Bluelake. The scanning time is stored in the field Exposure time (ms) on the Description tag.
• Fixed tests to be compatible with pytest>=8.0.0.
• Ensure in returns True for a valid data path (e.g. "Force HF/Force 1x" in file should return True).

Improvements

• ImageStack now closes any file handles it has open upon garbage collection.

Deprecations

• Deprecated GaussianMixtureModel.from_channel(). The class constructor now accepts Slice instances directly.
• Deprecated GaussianMixtureModel.label(). Use GaussianMixtureModel.state_path() instead. Note, the returned instance is type Slice rather than np.ndarray. The data can be accessed via model.state_path(channel_slice).data.
• Deprecated GaussianMixtureModel.exit_flag Use GaussianMixtureModel.fit_info() instead. Note, the returned instance is a GmmFitInfo dataclass with attributes matching the keys of the dict returned from exit_flag (along with bic and aic; see next point).
• Deprecated GaussianMixtureModel.bic and GaussianMixtureModel.aic properties. These values can now be accessed via the bic and aic properties of GaussianMixtureModel.fit_info.

Breaking changes (alpha functionality)

• trace_kwargs and label_kwargs are now keyword-only arguments for GaussianMixtureModel.plot().

Other changes

• Bump tifffile dependency to >=2022.7.28.

v1.3.1

Bug fix

• Fixed a bug in Scan.export_video() and ImageStack.export_video() which resulted in empty frames being written when exporting with channel data.

v1.3.0

New features

• Added option to export ImageStack and Scan stacks to movies correlated with channel data. Simply pass a Slice to the channel_slice parameter of Scan.export_video() or ImageStack.export_video().
• Added more options for plotting color channels for images:
  • Shortcuts "r", "g", and "b" can now be used for plotting single color channels in addition to "red", "green", and "blue".
  • Two-channel visualizations can be plotted using "rg", "gb", or "rb".
• Added option to filter tracks by duration in seconds using lk.filter_tracks(tracks, minimum_duration=duration_in_seconds).
• Added option to align plots vertically by passing vertical=True to Scan.plot_correlated and ImageStack.plot_correlated().
• Added duration property to KymoTrack which returns the duration (in seconds) that the track was observed.
• Added KymoTrackGroup.filter() to filter tracks in-place. tracks.filter(minimum_duration=2) is equivalent to tracks = lk.filter_tracks(tracks, minimum_duration=2).

Bug fixes

• Fixed a bug in Scan.plot() in which the default aspect ratio was calculated such that pixels always appeared square. For scans with non-square pixel sizes, this would result in distortion of the image.
• Fixed a bug in Slice.downsampled_like that would fail to raise an error due to a lack of overlap between the low frequency and high frequency channel when the high frequency channel starts within the last sample of the low frequency channel.
• Fixed lk.download_from_doi() to align with new Zenodo REST API.
• Don't store animation writer in a temporary variable as this results in a matplotlib error when attempting to export a movie on jupyter notebook.

Improvements

• Kymographs consisting of a single scan line now return a valid line_time_seconds. This allows certain downstream functionality, such as Kymo.plot().
• Issue a more descriptive error when attempting to compute a diffusion constant of a track with no points.
• Pylake can now handle kymographs that were erroneously stored in the Scan field. Kymographs with a pre-specified number of lines to record were incorrectly being marked on the timeline and exported as Scan instead of Kymograph in versions of Bluelake prior to 2.5.0.

v1.2.1

Bug fixes

• Fixed lk.download_from_doi() to align with new Zenodo REST API.
• Fixed a bug where the minimum length field of an exported KymoTrackGroup was formatted as an integer resulting in rounding errors when storing the tracks. Note that an incorrect minimum length can lead to biases when performing dwell time analysis. These values are now properly formatted as floating point numbers. The entry in the header was also changed to "minimum observable duration (seconds)" for additional clarity. This bug was introduced in version 1.2.0.
• Fixed a bug that prevented resaving a KymoTrackGroup loaded from an older version of Pylake.
• Fixed a bug that inadvertently made us rely on cachetools>=5.x. Older versions of cachetools did not pass the instance to the key function resulting in a TypeError: key() missing 1 required positional argument: '_' error when accessing cached properties or methods.
• Fixed a bug that could cause a division by zero while fitting power spectra with f_diode. The lower bound of f_diode was changed from 0 to 1.0 Hz. This change should not impact results unless users were getting failed calibrations with this error.
• Fixed a layout issue that made the sliders appear so narrow in jupyterlab that they were not visible.

v1.2.0

New features

• Added fitting mode "simultaneous" to lk.refine_tracks_gaussian() which enforces optimization bounds between the peak positions. This helps prevent lk.refine_tracks_gaussian() from reassigning points to the wrong track when a track momentarily disappears and overlap_strategy is set to "multiple" and refine_missing_frames is set to True. When fitting mode is set to "simultaneous", bounds ensure that the individual Gaussians cannot switch position. In addition, this mode uses a better initial guess for the peak amplitudes based on the maximum photon count observed in each range.
• Added the option to take into account discretization effects in DwelltimeModel by passing a discretization_timestep to the model when constructing it.
• Added the option to take into account discretization effects when performing dwell time analysis on a KymoTrackGroup. Simply pass discrete_model=True to KymoTrackGroup.fit_binding_times() to make use of this new functionality.
• Added the optional parameter loss_function to fit_power_spectrum(). Implemented loss functions are "gaussian" (default) and "lorentzian". The default corresponds to regular least-squares fitting, whereas "lorentzian" invokes a robust fitting method that is less susceptible to spurious peaks in the power spectrum which comes at the cost of a small bias in the estimates for a spectrum without noise peaks. Furthermore, no estimates of the errors in the fitted parameters are provided. This is beta functionality. While usable, this has not yet been tested in a large number of different scenarios. The API can still be subject to change without any prior deprecation notice!
• Added PowerSpectrum.identify_peaks() method to the PowerSpectrum class. This method uses probability to identify peaks in the spectrum that are not due to the movement of beads in an optical trap. This is beta functionality. While usable, this has not yet been tested in a large number of different scenarios. The API can still be subject to change without any prior deprecation notice!
• Added KymoTrack.plot_fit() and KymoTrackGroup.plot_fit() to show the fitted model obtained from gaussian refinement.
• Added the ability to specify a cropping region when exporting to an h5-file using file.save_as(filename, crop_time_range=(starting_timestamp, ending_timestamp)).
• Added method to create colormaps approximating a color from emission wavelength. See lk.colormaps.from_wavelength() for more information.
• Added support for accessing Kymo, Scan and PointScan by path (e.g. file["Kymograph"]["my_kymo"] or file["Kymograph/my_kymo"]).
• Added support for slicing PointScan.

Bug fixes

• Fixed issue in dwell time analysis that could lead to biased estimates for kymographs with very few events. Before this fix KymoTrackGroup.fit_binding_times() relied on the assumption that the shortest observed track is actually the minimum observable dwell time. This assumption is valid for kymographs with many events; however, this becomes problematic when multiple kymographs with few events each are analyzed globally. In this case, binding times will be underestimated. With this fix, the minimum observable dwell time is calculated from the kymograph scan line time and the set minimum track length.
  • The old (incorrect) behavior is maintained as default until the next major release (v2.0.0) to ensure backward compatibility.
  • To enable the fixed behavior immediately (recommended), specify observed_minimum=False when calling KymoTrackGroup.fit_binding_times().
  • To maintain the old legacy behavior use observed_minimum=True.
  • Note that CSVs exported from the kymotracking widget before v1.2.0 will contain insufficient metadata to make use of the improved analysis. To recover this metadata, use lk.filter_tracks() on the KymoTrackGroup with a specified min_length. This filters short events and stores the new minimum observable duration in the group.

Other changes

• File.save_as() data now allows passing in a single string for the omit_data parameter.
• Gracefully handle empty Scan after slicing. Previously, a slice operation on a Scan that resulted in no frames remaining raised a NotImplementedError. Now it returns an EmptyScan.
• Improved performance of Scan.pixel_time_seconds, Kymo.pixel_time_seconds and Kymo.line_time_seconds.
• Dropped opencv dependency which was only used for calculating rotation matrices and performing the affine transformations required for image alignment. Pylake now uses scikit-image for this purpose.
• Marked functions that take file paths as arguments with the os.PathLike type hint to idicate that pathlib.Path and similar types are also accepted (not just str).
• Use Unicode characters for µ and ² when plotting rather than TeX strings.

Deprecations

• Deprecated fitting mode "multiple" in lk.refine_tracks_gaussian() as it could lead to spurious track crossings. See the entry for the fitting mode "simultaneous" under New Features for more information.

v1.1.1

• Fixed parameter description for minimum length. It now correctly reads that increasing this parameter reduces tracking noise.
• Rarely used but heavy packages like opencv, scikit-image, and scikit-learn are no longer loaded eagerly with import lumicks.pylake. Rather, they are loaded on-demand the first time that a feature needs them. This makes importing pylake itself faster and mitigates potential third-party issues (e.g. this makes the first issue from the F.A.Q. less severe as it no longer affects all users).