Breaking Changes

A more detailed version history can be found in the Changelog.

BPReveal 7.x

BPReveal 7.0.0

When BPReveal 7.0.0 is released, the following breaking changes will occur:

Attempting to use a slice that goes beyond the limits of your PISA data will now
trigger an error. Has emitted a message since 5.1.0.
Using an importance hdf5 from before version 4.0.0 will now result in an
error instead of a deprecation warning.

BPReveal 6.x

BPReveal 6.0.0

When BPReveal 6.0.0 is released, the following breaking changes will occur:

The showModel tool will be removed since it just wraps a single keras function call, and getting graphical output requires two rather large dependencies.
interpretPisaFasta and interpretPisaBed are old names for interpretPisa. They exist only as symlinks in the bin/ directory, and using them has emitted a warning since 4.0.0. In BPReveal 6.0.0, the symlinks will be removed.
makePredictionsFasta and makePredictionsBed are old names for makePredictions. They exist only as symlinks in the bin/ directory, and using them has emitted a warning since 4.1.1. The old names will be removed.
Not including a correct-receptive-field field in your config to interpretPisa will no longer issue a warning - the correct receptive field will be applied by default.
If you want to get a tsv of seqlets from motifSeqletCutoffs, you will need to provide a modisco-window parameter in the configuration json. Omitting this has issued a warning and generated invalid coordinate data since 4.1.3.
The plots.py module in the tools directory will be removed. Its replacement, plotting.py, was introduced in 4.2.0 and is part of the main repository.
The addNoise tool will be removed. It turns out that it’s not useful.
When doing PISA interpretation on a fasta, you must call the fasta fasta-file instead of sequence-fasta. (Has emitted a warning since 4.0.0.)
prepareBed will no longer accept a list of bigwigs without head information. The program currently spits out warnings when you do this, and these will become an error.

BPReveal 5.x

BPReveal 5.1.0

When BPReveal 5.1.0 was released, the following breaking changes occurred.

If you provide a sequence that is longer than a model’s input-length to easyPredict, it used to crash with an invalid input size error. It will now make enough predictions to cover the whole sequence you provided and return a stitched profile. This will only be an issue if you were, for some reason, causing easyPredict() to crash and then catching that exception. For any sane use case, this will not cause a problem.
Quite a lot of refactoring was done inside interpretUtils. Importantly, FlatRunner and PisaRunner are now gone, they have been unified into a new class called InterpRunner that lets you use your own metric for shapping.
interpretUtils.py and shap.py were moved to the internal/ directory since that’s really where they belong.

BPReveal 5.0.0

When BPReveal 5.0.0 was released, the following breaking changes occurred:

The first argument to models.transformationModel was renamed to get rid of a name collision that pylint gets upset about.
The correct-receptive-field flag in interpretPisa, introduced in 4.1.2, switched from being false by default to being true by default. This fixes an off-by-one bug in how receptive field was calculated.
The dumpModiscoSeqlets tool was removed, since it’s not useful.
BPReveal now uses Tensorflow 2.16 and Keras 3.0. This will cause some breaking changes. Models are saved on disk now using a .keras extension because Keras 3.0 enforces this.
Keras 3.0 only reports a whole-model loss instead of a per-output loss, which caused the names of the reported metrics to change. Instead of solo_logcounts_nanog_loss and solo_profile_nanog_loss, these are now solo_logcounts_nanog_reweightable_mse and solo_profile_nanog_multinomial_nll. Technically, these are now metrics and not losses, but that should make no difference in practice.
The shap code was further trimmed down. The names of the arguments to combine_mult_and_diffref were changed to camelCase to match the style of BPReveal.

BPReveal 4.x

BPReveal 4.3.0

Some of the arguments in internal.plotUtils were renamed to improve consistency.
The internal implementation of transformation models was changed so that they can be interpreted with shap. If you were messing with the internal layers in a transformation model, they’re different now. If you’re not probing at the internal layers, this will have no effect - the API is unchanged.

BPReveal 4.2.0

BPReveal now uses tensorflow 2.16 and Python 3.12. It still uses the legacy Keras, though. If you were manually working with Keras, you will need to import tf_keras instead.
The tools.plots module has been retired. It has been replaced by plotting, which exposes a semi-coherent API and has generally been cleaned way up. The old module now emits a warning, but it will stay around until at least version 6.0.0.
The names of the type variables in the gaOptimise were switched to UPPER_CASE to match the rest of the project. This should have no effect on user code.

BPReveal 4.1.4

The shap code was replaced with the current release from upstream. This should not break anything unless you were doing something really weird.

BPReveal 4.1.3

With the creation of the new Seqlet class, several arrays that used to be in the Pattern class have been removed. If you were creating Patterns in your own code, you will need to instead refer to the seqlet arrays. No file formats are changed by this.

BPReveal 4.1.1

The name of the counts head in a transformation model that uses bias counts changed from combined_log_counts to combined_logcounts, which might possibly break some very obscure use case. This change was necessary to fix a couple bugs with adaptive counts loss and showTrainingProgress.
To allow the prediction script to work with very large bed files, some refactoring was done. This included moving functions to add metadata to hdf5 files into a new module, internal.predictUtils. If you were calling them from the old makePredictionsFasta.py module, they have moved.
A new library, libslide, has been added. You will need to re-run make (or reinstall the environment) to use it.

BPReveal 4.1.0

The output format from training was totally re-written to be easier to use in log files. A new tool, showTrainingProgress can be used to get a nice view of your model’s progress as it trains up.

BPReveal 4.0.2

A few variables deep inside BPReveal were changed from snake_case to the preferred style for BPReveal, camelCase. This should not have any effect unless you were digging deep inside the code.

BPReveal 4.0.0

The following breaking changes occurred when BPReveal 4.0.0 was released:

The chromosome list in the hdf5 files produced by interpretFlat stored chromosome information as strings, unlike all other output file formats. This changed so that chromosomes are numbered. shapToBigwig and the motif scanning utilities now emit warnings if they detect an old-style importance hdf5. This will become an error in 5.0.0.
The adaptive loss algorithm required me to implement a custom mse loss. In 3.6, I sneakily called it "mse" so you didn’t have to add another custom object to scope when you load a new model. This loss will be renamed "reweightableMse" and you’ll have to add it to the custom object scopes when you load a model. Since the full new loss includes a tensor that must be created beforehand, losses will include a dummy version that you can use to load, but not train, a model. See Adaptive Counts Loss for the algorithm.

BPReveal 3.x

BPReveal 3.6.0

The predictToBigwig script now averages the values in overlapping regions instead of taking the leftmost base. This may result in small changes in generated bigwigs.
In order to accommodate the adaptive loss algorithm (Adaptive Counts Loss), some of the layer names in transformation models were changed. If you were depending on these layer names, I’m curious to know how you got yourself in that situation.

BPReveal 3.5.0

BPReveal now uses Python 3.11, instead of 3.10. Users must re-build the libjaccard library for the new Python version.

BPReveal 3.0.0

You must specify a "remove-overlaps" field in configuration files for prepareBed.
cropdown layers were removed as an option for transformation models.
The transformation model configuration file calls the input length input-length instead of sequence-input-length.