Merge pull request #106 from aertslab/1.3.0

1.3.0

README.md

@@ -68,7 +68,7 @@ For questions and help requests, please use the [issue tracker][issue-tracker].
 
 ## Citation
 
-Kempynck, N., Mahieu, L., Ekşi, E. C., Konstantakos, V., Blaauw, C., De Winter, S., Hulselmans, G., Taskiran, I., & Aerts, S. (2024). CREsted: Cis Regulatory Element Sequence Training, Explanation, and Design (1.2.0). Zenodo. https://10.5281/zenodo.13918932
+Kempynck, N., Mahieu, L., Ekşi, E. C., Konstantakos, V., Blaauw, C., De Winter, S., Hulselmans, G., Taskiran, I., & Aerts, S. (2024). CREsted: Cis Regulatory Element Sequence Training, Explanation, and Design (1.3.0). Zenodo. https://10.5281/zenodo.13918932
 
 ## Choosing your backend
 

docs/changelog.md

@@ -1,5 +1,65 @@
 # Release Notes
 
+## 1.3.0
+
+This is a big release wherein we introduce our model repository and do a functional refactoring of our `tl.Crested` class.
+
+### Features
+
+-   new `crested.get_model` function to fetch models from crested model repository
+-   new `enformer` and `borzoi` model options in the crested zoo, as well as scripts for converting weights to keras format.
+-   new cut site bigwigs option for mouse cortex dataset
+-   new crested model repository in the readthedocs with model descriptions.
+-   new pattern clustering plot `pl.patterns.clustermap_with_pwm_logos` that shows PWM logo plots below the heatmap.
+-   Extra parameters options in modisco calculations and plotting regarding allowed seqlets per cluster and top_n_regions selection.
+-   option to color lines in gene locus scoring plotting
+-   extra ylim option in `crested.pl.bar.prediction`
+-   gene locus scoring plotting improvements
+
+## Bugfixes
+
+-   importing bigwigs now correctly accounts for regions that were removed due to chromsizes
+
+## Notebooks
+
+-   Rewrote the tutorials to use the new functional API (WIP).
+-   Expanded on the enhancer design section
+
+## Functional Refactor of crested.tl.Crested(...) class
+
+In this large refactor we're moving everything from the Crested class that does not use both a model and the AnnDatamodule out to a new \_tools.py module where everything will be functional.
+All the old functions remain in the Crested class for backward compatibility (for now) but will now raise a deprecation warning.
+
+We're giving up a bit of clarity for ease of use by combining functions that do the same on different inputs into one single function.
+
+### Equivalent new functions
+
+-   `tl.Crested.get_embeddings(...)` ---> `tl.extract_layer_embeddings(...)`
+-   `tl.Crested.predict(...)` --->` tl.predict(...)`
+-   `tl.Crested.predict_regions(...)` ---> `tl.predict(...)`
+-   `tl.Crested.predict_sequence(...)` ---> `tl.predict(...)`
+-   `tl.Crested.score_gene_locus(...)` ---> `tl.score_gene_locus(...)`
+-   `tl.Crested.calculate_contribution_scores(...)` ---> `tl.contribution_scores(...)`
+-   `tl.Crested.calculate_contribution_scores_regions(...)` ---> `tl.contribution_scores(...)`
+-   `tl.Crested.calculate_contribution_scores_sequence(...)` ---> `tl.contribution_scores(...)`
+-   `tl.Crested.calculate_contribution_scores_enhancer_design(...)` ---> `tl.contribution_scores(...)`
+-   `tl.Crested.tfmodisco_calculate_and_save_contribution_scores_sequences` ---> `tl.contribution_scores_specific(...)`
+-   `tl.Crested.tfmodisco_calculate_and_save_contribution_scores` ---> `tl.contribution_scores(...)`
+-   `tl.Crested.enhancer_design_motif_implementation` ---> `tl.enhancer_design_motif_insertion`
+-   `tl.Crested.enhancer_design_in_silico_evolution` ---> `tl.enhancer_design_in_silico_evolution`
+
+### New functions
+
+Some utility functions were hidden inside the Crested class but required to be made explicit.
+
+-   `utils.calculate_nucleotide_distribution` (advised for enhancer design)
+-   `utils.derive_intermediate_sequences` (required for inspecting intermediate results from enhancer design)
+
+### New behaviour
+
+-   All functions that accept a model can now also accept lists of models, in which case the results will be averaged across models.
+-   All functions use a similar api, namely they expect some 'input' that can be converted to a one hot encoding (sequences, region names, anndatas with region names), but now the conversion happens behind the scenes so the user doesn't have to worry about this and we don't have a separate function per input format.
+
 ## 1.2.1
 
 ### Bug Fixes

docs/howtocite.md

@@ -0,0 +1,5 @@
+# How To Cite
+
+If you use the CREsted package in your work, please cite it as follows:
+
+Kempynck, N., Mahieu, L., Ekşi, E. C., Konstantakos, V., Blaauw, C., De Winter, S., Hulselmans, G., Taskiran, I., & Aerts, S. (2024). CREsted: Cis Regulatory Element Sequence Training, Explanation, and Design (1.3.0). Zenodo. https://10.5281/zenodo.13918932

docs/index.md

@@ -13,4 +13,6 @@ models/index
 changelog
 contributing
 references
+howtocite
+license
 ```

docs/license.md

@@ -0,0 +1,59 @@
+# License
+
+Academic Non-commercial Software License Agreement
+
+The Licensed Software is developed by and on behalf of the Laboratory of Computational Biology of VIB-KU Leuven and is owned by VIB vzw, located at Rijvisschestraat 120, B-9052 Zwijnaarde, Belgium (hereinafter referred to as "VIB"). By downloading or installing the Licensed Software, the user agrees with the terms and conditions below.
+
+Definitions
+
+“Licensed Software” shall mean CREsted as available on GitHub.
+
+"Effective Date" shall mean the date on which you download or install CREsted (as available on GitHub) on your system and which provide you access to the CREsted tool.
+
+“Commercial Purposes” shall include (1) the use of Licensed Software to provide a service, information or data that is directly or indirectly conveyed to any third party against compensation, (2) any type of transfer of the Licensed Software for compensation, and (3) any other use of Licensed Software that supports commercial entities.
+
+License
+
+1. Licensed Software is the work of the Aerts lab. The copyright in Licensed Software is owned by VIB.
+
+2. Subject to the terms and conditions of this Agreement, VIB hereby grants and the user accepts a non-exclusive, non-transferable license to use the Licensed Software for strictly internal academic research use only, on your own behalf or on behalf of your institution, and not for Commercial Purposes.
+
+3. The user confirms to be an academic user. For academic users, there is no license fee.
+
+4. The user shall acknowledge VIB as the provider of Licensed Software and shall include the following reference “Kempynck et al., CREsted: Cis Regulatory Element Sequence Training, Explanation, and Design. Zenodo (2024) 10.5281/zenodo.13320756: 2024-08” in any manuscript describing data obtained using Licensed Software.
+
+5. This license does not entitle the user to receive from VIB hard-copy documentation, technical support, telephone assistance, or enhancements or updates to the Licensed Software, and nothing contained herein shall be interpreted as to require VIB, its faculty, employees or students to provide maintenance, installation services, debugging, consultation or end-user support of any kind.
+
+6. The title and copyright to Licensed Software and any associated programs and documentation shall remain with VIB. The user agrees to preserve the same.
+
+7. The user agrees not to make any copies of Licensed Software except for use in the user’s laboratory, without VIB’s prior written consent. The user agrees to place the appropriate copyright notice on any such copies.
+
+8. The user shall not distribute Licensed Software to other laboratories within user’s institution. The user shall not transfer Licensed Software to another location or person outside of user’s institution without VIB’s prior and written permission.
+
+9. The user shall not market or otherwise benefit commercially from any product utilizing any portion of Licensed Software, nor any derivative works of Licensed Software, without first entering into a separate commercial license with VIB.
+
+10. Except as otherwise expressly permitted in this Agreement, the user must not (i) modify or create any derivative works of the Licensed Software or documentation, including customization, translation or localization; (ii) decompile, disassemble, reverse engineer, or otherwise attempt to derive the source code for the Licensed Software; (iii) remove or alter any trademark, logo, copyright or other proprietary notices, legends, symbols or labels in the Licensed Software.
+
+11. The user acknowledges that the Licensed Software is proprietary to VIB. The software code shall be treated as trade secrets and confidential information of VIB, and the user agrees to use all reasonable efforts to hold the same in confidence. The user’s obligation for confidentiality shall not extend to any information which (i) is or becomes generally available to the public, (ii) is already known to or subsequently disclosed by third parties to the user and at its free disposal, or (iii) is independently developed by the user or its affiliates without the use of the confidential information disclosed by VIB, or (iv) is required by law or legal process to be disclosed.
+
+12. The user acknowledges that Licensed Software is a research tool and provided free of charge, it is only provided “as is”. VIB makes no representations or warranties of any type whatsoever, express or implied, regarding the Licensed Software. VIB expressly disclaims all representations and warranties regarding the Licensed Software, including but not limited to any representations or warranties of merchantability or fitness for any particular application or that the use of the Licensed Software will not infringe any patents, copyrights or trademarks or other rights of third parties, or any warranty that the rights and licenses granted hereunder comprise all the rights and licenses necessary or desirable to use the Licensed Software for internal non-commercial research purposes as permitted by this Agreement. The entire risk as to the quality and performance of the Licensed Software is borne by the user.
+
+13. VIB shall not be responsible for losses of any kind resulting from the use of Licensed Software, and can in no way provide compensation for any losses sustained, including but not limited to, any obligation, liability, right, claim or remedy for tort, or for any actual or alleged infringement of patents, copyrights, trade secrets, or similar rights of third parties, nor any business expense, machine downtime or damages caused by any deficiency, defect or error in Licensed Software or mal-function thereof, nor any incidental or consequential damages, however caused.
+
+14. The user will indemnify, defend and hold harmless VIB, its directors, officers, employees and agents from and against all liability, losses, damages and expenses (including attorney’s fees and costs) arising out of any claims, demands, actions or other proceedings made or instituted by any third party against any of them and arising out of or relating to any breach of this Agreement by the user, or any use of the Licensed Software by the user, except insofar as such claims or liability result from VIB’s gross negligence or willful misconduct.
+
+15. This Agreement and the license rights granted herein shall become effective as of the date the user downloaded the Licensed Software and shall continue in full force until the user deletes the Licensed Software and any and all related files from the user’s computing system, unless terminated in accordance with this Section. Upon one party's breach of any agreement, covenant, or representation made in this Agreement, the agreement will automatically end thirty (30) days after such breach. Either party shall have the right, at any time, to terminate this Agreement without cause by written notice to the other party specifying the date of termination. Upon termination, the user shall destroy all full and partial copies of the Licensed Software. The user shall forward written notice to VIB that all programs containing Licensed Software have been deleted from all computer libraries and storage or memory devices and are no longer stored therein.
+
+16. This Agreement shall be construed in accordance with the laws of Belgium. The courts of Belgium shall have exclusive jurisdiction.
+
+17. The parties agree that this Agreement is the complete and exclusive agreement among the parties and supersedes all proposals and prior agreements whether written or oral, and all other communications among the parties relating to the subject matter of this Agreement. This Agreement cannot be modified except in writing and signed by both parties. Failure by either party at any time to enforce any of the provisions of this Agreement shall not constitute a waiver by such party of such provision nor in any way affect the validity of this Agreement.
+
+18. The invalidity of singular provisions does not affect the validity of the entire understanding. The parties are obligated, however, to replace the invalid provisions by a regulation, which comes closest to the economic intent of the invalid provision. The same shall apply mutatis mutandis in case of a gap.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

docs/references.bib

@@ -30,3 +30,22 @@ @article{Zhang_2024
     volume = {21},
     pages = {217--227}
 }
+
+@misc{Pampari_Bias_factorized_base-resolution_2023,
+  author = {Pampari, Anusri and Shcherbina, Anna and Nair, Surag and Schreiber, Jacob and Patel, Aman and Wang, Austin and Kundu, Soumya and Shrikumar, Avanti and Kundaje, Anshul},
+  doi = {10.5281/zenodo.7567627},
+  month = jan,
+  title = {{Bias factorized, base-resolution deep learning models of chromatin accessibility reveal cis-regulatory sequence syntax, transcription factor footprints and regulatory variants.}},
+  url = {https://github.com/kundajelab/chrombpnet},
+  version = {0.1.1},
+  year = {2023}
+}
+
+@article{Huey_Bigtools_a_high-performance_2024,
+  author = {Huey, Jack and Abdennur, Nezar},
+  doi = {10.1093/bioinformatics/btae350},
+  journal = {Bioinformatics},
+  title = {{Bigtools: a high-performance BigWig and BigBed library in Rust}},
+  url = {https://doi.org/10.1093/bioinformatics/btae350},
+  year = {2024}
+}

pyproject.toml

@@ -4,7 +4,7 @@ requires = ["hatchling"]
 
 [project]
 name = "crested"
-version = "1.2.1"
+version = "1.3.0"
 description = "CREsted: Cis-Regulatory Element Sequence Training, Explanation, and Design"
 readme = "README.md"
 requires-python = ">=3.9"