levseq 1.5__tar.gz → 1.5.1__tar.gz

{levseq-1.5/levseq.egg-info → levseq-1.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: levseq
-Version: 1.5
+Version: 1.5.1
 Home-page: https://github.com/fhalab/levseq/
 Author: Yueming Long, Ariane Mora, Francesca-Zhoufan Li, Emre Gursoy
 Author-email: ylong@caltech.edu
@@ -74,43 +74,78 @@ Figure 1: Overview of the LevSeq variant sequencing workflow using Nanopore tech
 - **Reversed workflow architecture**: LevSeq 2.0 will perform alignment first, then demultiplexing (rather than the current demultiplexing-first approach), resolving issues with forward and reverse read handling
 - **Improved accuracy**: These changes will provide more robust demultiplexing and variant calling across diverse experimental conditions
 
-**Please reach out to us at ylong@caltech.edu if you are planning to order barcoded primers now**
+**If you are planning to order barcoded primers now, or need detailed help with troubleshooting or barcode design, please reach out at [lyming2021@gmail.com](mailto:lyming2021@gmail.com).**
 
 ## Notes
 
-LevSeq was designed for epPCR and SSM experiments, however, we are currently extending it to work for other enzyme engineering designs as well, the current features are under development:
+LevSeq was designed for epPCR and SSM experiments. We are also extending it to support additional enzyme engineering designs. Current features under development include:
 
-1. Insertion handling (see version 4.1.3) - thanks to  Brian Zhong for his contributions to this section!
-2. Gene calling (handling different genes, use the `--oligopool` flag)
+1. Insertion handling (see version 4.1.3). Thanks to Brian Zhong for contributions to this section.
+2. Gene calling for experiments with different genes, using the `--oligopool` flag.
 
-If you notice any issues with new features or have adapted the LevSeq code for your own use cases, we would love community contributions! Please submit either an issue, or a pull request and we will aim to incorperate the changes.
+If you notice issues with new features or have adapted LevSeq for your own use case, community contributions are welcome. Please submit an issue or pull request and we will aim to incorporate the changes.
 
 Performance update: demultiplexing now runs in parallel batches of 8 plates and input FASTQs are staged once per run, improving throughput on multi-core systems.
 
+Recent repository polish:
+- Faster imports: `import levseq` no longer initializes visualization libraries unless they are needed.
+- Cleaner run startup: plotting dependencies are loaded only when platemaps are generated.
+- Packaging cleanup: bundled barcode files and demultiplex binaries are now declared through package discovery.
+- Git hygiene: local `node_modules/` folders are ignored.
+
 ## Quick Start
 
-Note the current stable version is: `1.5`, the latest version is `1.5`. 
+Note the current stable version is: `1.5.1`, the latest version is `1.5.1`.
 
 For stable releases these are made available via docker and pip. For latest versions, please clone the repo and install locally (see *Local development or install of latest version* below).
 
+### How to Run LevSeq
+
+Before running LevSeq, prepare:
+- A folder containing Oxford Nanopore basecalled FASTQ files, usually from a `fastq_pass` directory.
+- A reference CSV file with the columns `barcode_plate`, `name`, and `refseq` (see [Reference File Format](#reference-file-format-refcsv)).
+- A run name, which LevSeq uses as the output folder name.
+
+The basic command format is:
+
+```bash
+levseq <run_name> <path_to_fastq_folder> <path_to_ref_csv>
+```
+
+Example:
+
+```bash
+levseq my_experiment /path/to/fastq_pass /path/to/ref.csv
+```
+
+LevSeq writes results to an output folder named after `<run_name>`. Key outputs include `variants.csv`, `visualization_partial.csv`, result CSV files, logs, and interactive platemap HTML files.
+
+Common run options:
+- Use `--output /path/to/output` to choose where the run folder is created.
+- Use `--skip_demultiplexing` if reads have already been demultiplexed.
+- Use `--skip_variantcalling` if you only want to run demultiplexing.
+- Use `--oligopool` for experiments with multiple genes or references per barcode plate.
+- Use `--show_msa` to include multiple sequence alignment views in the output.
+
 ### Docker Installation (Recommended)
 
 1. Install Docker: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
 2. Pull the appropriate image:
    ```bash
    # For Linux/Windows x86 systems:
-   docker pull yueminglong/levseq:levseq-1.4-x86
+   docker pull yueminglong/levseq:levseq-1.5.1-x86
    
    # For Mac M-series chips (M1, M2, M3, M4):
-   docker pull yueminglong/levseq:levseq-1.4-arm64
+   docker pull yueminglong/levseq:levseq-1.5.1-arm64
    ```
 3. Run LevSeq:
    ```bash
-   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv
+   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv
    ```
+   Replace `levseq-1.5.1-arm64` with the image tag that matches your platform and release.
 4. Connect function data to your sequence data
    ```bash
-   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv --fitness_files "levseq_results/20250712_epPCR_Q06714_37.csv,levseq_results/20250712_epPCR_Q06714_39.csv,levseq_results/20250712_epPCR_Q06714_40.csv" --smiles 'O=P(OC1=CC=CC=C1)(OC2=CC=CC=C2)OC3=CC=CC=C3>>O=P(O)(OC4=CC=CC=C4)OC5=CC=CC=C5' --compound dPPi --variant_df "levseq_results/visualization_partial.csv"
+   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv --fitness_files "levseq_results/20250712_epPCR_Q06714_37.csv,levseq_results/20250712_epPCR_Q06714_39.csv,levseq_results/20250712_epPCR_Q06714_40.csv" --smiles 'O=P(OC1=CC=CC=C1)(OC2=CC=CC=C2)OC3=CC=CC=C3>>O=P(O)(OC4=CC=CC=C4)OC5=CC=CC=C5' --compound dPPi --variant_df "levseq_results/visualization_partial.csv"
    ```
 ### Pip Installation (Mac/Linux only)
 
@@ -145,11 +180,11 @@ brew install gcc@13 gcc@14
    levseq my_experiment /path/to/data/ /path/to/ref.csv  "LCMS_file_{barcode1}.csv,LCMS_file_{barcode2}.csv," --smiles 'reaction_smiles_string' --compound "name_of_compound_in_LCMS_file" --variant_df "visualization_partial.csv"
    ```
 
-Note for function data we currently expect a LCMS file e.g. with the columns: 
+For function data, LevSeq currently expects LCMS files with these columns:
 - `Sample Vial Number` (corresponding to the well that the sample was from). 
 - `Area` (which becomes fitness value). 
 - `Compound Name` which is the name of the compound we filter for that is passed as a parameter.
-- The last `_X.csv` needs to be the barcode number to match that sample to your plate e.g. if you ran LevSeq with barcode 33 for plate 2 you need to have `_33.csv` for the fitness file for plate 2. e.g. `some_fitnes_for_plate_2_33.csv`.
+- The final `_X.csv` suffix should contain the barcode number used to match that sample to the correct plate. For example, if plate 2 used barcode 33, the fitness file should end in `_33.csv`, such as `some_fitness_for_plate_2_33.csv`.
 
 
 ## Data and Visualization
@@ -188,6 +223,10 @@ For oligopool experiments (multiple proteins per plate), use:
 - `--output`: Custom save location (defaults to current directory)
 - `--show_msa`: Show multiple sequence alignment for each well
 - `--oligopool`: Process data as oligopool experiment
+- `--fitness_files`: Comma-separated LCMS or function-data CSV files to join with sequence results
+- `--smiles`: Reaction SMILES string used when joining function data
+- `--compound`: Compound name to filter in the function-data files
+- `--variant_df`: LevSeq variant dataframe to join with function data, usually `visualization_partial.csv`
 
 ## Step-by-Step Tutorial
 
@@ -198,7 +237,7 @@ For oligopool experiments (multiple proteins per plate), use:
 2. **Run LevSeq**:
    ```bash
    # Via Docker
-   docker run --rm -v "/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv
+   docker run --rm -v "/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv
    
    # Via pip
    levseq my_experiment /path/to/data/ /path/to/ref.csv
@@ -229,7 +268,7 @@ conda create --name levseq python=3.10
 git clone git@github.com:fhalab/LevSeq.git
 cd LevSeq
 python setup.py sdist bdist_wheel
-pip install dist/levseq-1.4.3.tar.gz
+pip install dist/levseq-1.5.1.tar.gz
 ```
 
 ## Citing LevSeq
@@ -248,4 +287,4 @@ If you find LevSeq useful, please cite our paper:
 
 ## Contact
 
-Leave a feature request in the issues or reach us via [email](mailto:levseqdb@gmail.com).
+For detailed questions, troubleshooting, barcode design support, or feature requests, email [lyming2021@gmail.com](mailto:lyming2021@gmail.com). Reproducible bugs and public feature discussions are also welcome as GitHub issues.

{levseq-1.5 → levseq-1.5.1}/README.md

@@ -15,43 +15,78 @@ Figure 1: Overview of the LevSeq variant sequencing workflow using Nanopore tech
 - **Reversed workflow architecture**: LevSeq 2.0 will perform alignment first, then demultiplexing (rather than the current demultiplexing-first approach), resolving issues with forward and reverse read handling
 - **Improved accuracy**: These changes will provide more robust demultiplexing and variant calling across diverse experimental conditions
 
-**Please reach out to us at ylong@caltech.edu if you are planning to order barcoded primers now**
+**If you are planning to order barcoded primers now, or need detailed help with troubleshooting or barcode design, please reach out at [lyming2021@gmail.com](mailto:lyming2021@gmail.com).**
 
 ## Notes
 
-LevSeq was designed for epPCR and SSM experiments, however, we are currently extending it to work for other enzyme engineering designs as well, the current features are under development:
+LevSeq was designed for epPCR and SSM experiments. We are also extending it to support additional enzyme engineering designs. Current features under development include:
 
-1. Insertion handling (see version 4.1.3) - thanks to  Brian Zhong for his contributions to this section!
-2. Gene calling (handling different genes, use the `--oligopool` flag)
+1. Insertion handling (see version 4.1.3). Thanks to Brian Zhong for contributions to this section.
+2. Gene calling for experiments with different genes, using the `--oligopool` flag.
 
-If you notice any issues with new features or have adapted the LevSeq code for your own use cases, we would love community contributions! Please submit either an issue, or a pull request and we will aim to incorperate the changes.
+If you notice issues with new features or have adapted LevSeq for your own use case, community contributions are welcome. Please submit an issue or pull request and we will aim to incorporate the changes.
 
 Performance update: demultiplexing now runs in parallel batches of 8 plates and input FASTQs are staged once per run, improving throughput on multi-core systems.
 
+Recent repository polish:
+- Faster imports: `import levseq` no longer initializes visualization libraries unless they are needed.
+- Cleaner run startup: plotting dependencies are loaded only when platemaps are generated.
+- Packaging cleanup: bundled barcode files and demultiplex binaries are now declared through package discovery.
+- Git hygiene: local `node_modules/` folders are ignored.
+
 ## Quick Start
 
-Note the current stable version is: `1.5`, the latest version is `1.5`. 
+Note the current stable version is: `1.5.1`, the latest version is `1.5.1`.
 
 For stable releases these are made available via docker and pip. For latest versions, please clone the repo and install locally (see *Local development or install of latest version* below).
 
+### How to Run LevSeq
+
+Before running LevSeq, prepare:
+- A folder containing Oxford Nanopore basecalled FASTQ files, usually from a `fastq_pass` directory.
+- A reference CSV file with the columns `barcode_plate`, `name`, and `refseq` (see [Reference File Format](#reference-file-format-refcsv)).
+- A run name, which LevSeq uses as the output folder name.
+
+The basic command format is:
+
+```bash
+levseq <run_name> <path_to_fastq_folder> <path_to_ref_csv>
+```
+
+Example:
+
+```bash
+levseq my_experiment /path/to/fastq_pass /path/to/ref.csv
+```
+
+LevSeq writes results to an output folder named after `<run_name>`. Key outputs include `variants.csv`, `visualization_partial.csv`, result CSV files, logs, and interactive platemap HTML files.
+
+Common run options:
+- Use `--output /path/to/output` to choose where the run folder is created.
+- Use `--skip_demultiplexing` if reads have already been demultiplexed.
+- Use `--skip_variantcalling` if you only want to run demultiplexing.
+- Use `--oligopool` for experiments with multiple genes or references per barcode plate.
+- Use `--show_msa` to include multiple sequence alignment views in the output.
+
 ### Docker Installation (Recommended)
 
 1. Install Docker: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
 2. Pull the appropriate image:
    ```bash
    # For Linux/Windows x86 systems:
-   docker pull yueminglong/levseq:levseq-1.4-x86
+   docker pull yueminglong/levseq:levseq-1.5.1-x86
    
    # For Mac M-series chips (M1, M2, M3, M4):
-   docker pull yueminglong/levseq:levseq-1.4-arm64
+   docker pull yueminglong/levseq:levseq-1.5.1-arm64
    ```
 3. Run LevSeq:
    ```bash
-   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv
+   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv
    ```
+   Replace `levseq-1.5.1-arm64` with the image tag that matches your platform and release.
 4. Connect function data to your sequence data
    ```bash
-   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv --fitness_files "levseq_results/20250712_epPCR_Q06714_37.csv,levseq_results/20250712_epPCR_Q06714_39.csv,levseq_results/20250712_epPCR_Q06714_40.csv" --smiles 'O=P(OC1=CC=CC=C1)(OC2=CC=CC=C2)OC3=CC=CC=C3>>O=P(O)(OC4=CC=CC=C4)OC5=CC=CC=C5' --compound dPPi --variant_df "levseq_results/visualization_partial.csv"
+   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv --fitness_files "levseq_results/20250712_epPCR_Q06714_37.csv,levseq_results/20250712_epPCR_Q06714_39.csv,levseq_results/20250712_epPCR_Q06714_40.csv" --smiles 'O=P(OC1=CC=CC=C1)(OC2=CC=CC=C2)OC3=CC=CC=C3>>O=P(O)(OC4=CC=CC=C4)OC5=CC=CC=C5' --compound dPPi --variant_df "levseq_results/visualization_partial.csv"
    ```
 ### Pip Installation (Mac/Linux only)
 
@@ -86,11 +121,11 @@ brew install gcc@13 gcc@14
    levseq my_experiment /path/to/data/ /path/to/ref.csv  "LCMS_file_{barcode1}.csv,LCMS_file_{barcode2}.csv," --smiles 'reaction_smiles_string' --compound "name_of_compound_in_LCMS_file" --variant_df "visualization_partial.csv"
    ```
 
-Note for function data we currently expect a LCMS file e.g. with the columns: 
+For function data, LevSeq currently expects LCMS files with these columns:
 - `Sample Vial Number` (corresponding to the well that the sample was from). 
 - `Area` (which becomes fitness value). 
 - `Compound Name` which is the name of the compound we filter for that is passed as a parameter.
-- The last `_X.csv` needs to be the barcode number to match that sample to your plate e.g. if you ran LevSeq with barcode 33 for plate 2 you need to have `_33.csv` for the fitness file for plate 2. e.g. `some_fitnes_for_plate_2_33.csv`.
+- The final `_X.csv` suffix should contain the barcode number used to match that sample to the correct plate. For example, if plate 2 used barcode 33, the fitness file should end in `_33.csv`, such as `some_fitness_for_plate_2_33.csv`.
 
 
 ## Data and Visualization
@@ -129,6 +164,10 @@ For oligopool experiments (multiple proteins per plate), use:
 - `--output`: Custom save location (defaults to current directory)
 - `--show_msa`: Show multiple sequence alignment for each well
 - `--oligopool`: Process data as oligopool experiment
+- `--fitness_files`: Comma-separated LCMS or function-data CSV files to join with sequence results
+- `--smiles`: Reaction SMILES string used when joining function data
+- `--compound`: Compound name to filter in the function-data files
+- `--variant_df`: LevSeq variant dataframe to join with function data, usually `visualization_partial.csv`
 
 ## Step-by-Step Tutorial
 
@@ -139,7 +178,7 @@ For oligopool experiments (multiple proteins per plate), use:
 2. **Run LevSeq**:
    ```bash
    # Via Docker
-   docker run --rm -v "/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv
+   docker run --rm -v "/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv
    
    # Via pip
    levseq my_experiment /path/to/data/ /path/to/ref.csv
@@ -170,7 +209,7 @@ conda create --name levseq python=3.10
 git clone git@github.com:fhalab/LevSeq.git
 cd LevSeq
 python setup.py sdist bdist_wheel
-pip install dist/levseq-1.4.3.tar.gz
+pip install dist/levseq-1.5.1.tar.gz
 ```
 
 ## Citing LevSeq
@@ -189,4 +228,4 @@ If you find LevSeq useful, please cite our paper:
 
 ## Contact
 
-Leave a feature request in the issues or reach us via [email](mailto:levseqdb@gmail.com).
+For detailed questions, troubleshooting, barcode design support, or feature requests, email [lyming2021@gmail.com](mailto:lyming2021@gmail.com). Reproducible bugs and public feature discussions are also welcome as GitHub issues.

levseq-1.5.1/levseq/__init__.py

@@ -0,0 +1,215 @@
+###############################################################################
+#                                                                             #
+#    This program is free software: you can redistribute it and/or modify     #
+#    it under the terms of the GNU General Public License as published by     #
+#    the Free Software Foundation, either version 3 of the License, or        #
+#    (at your option) any later version.                                      #
+#                                                                             #
+#    This program is distributed in the hope that it will be useful,          #
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of           #
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            #
+#    GNU General Public License for more details.                             #
+#                                                                             #
+#    You should have received a copy of the GNU General Public License        #
+#    along with this program. If not, see <http://www.gnu.org/licenses/>.     #
+#                                                                             #
+###############################################################################
+
+__title__ = 'levseq'
+__description__ = 'LevSeq nanopore sequencing'
+__url__ = 'https://github.com/fhalab/levseq/'
+__version__ = '1.5.1'
+__author__ = 'Yueming Long, Ariane Mora, Francesca-Zhoufan Li, Emre Gursoy'
+__author_email__ = 'ylong@caltech.edu'
+__license__ = 'GPL3'
+
+from importlib import import_module
+import sys as _sys
+
+
+_LAZY_MODULES = {
+    'cmd': 'levseq.cmd',
+    'filter_orientation': 'levseq.filter_orientation',
+    'globals': 'levseq.globals',
+    'interface': 'levseq.interface',
+    'run_levseq': 'levseq.run_levseq',
+    'simulation': 'levseq.simulation',
+    'user': 'levseq.user',
+    'utils': 'levseq.utils',
+    'variantcaller': 'levseq.variantcaller',
+    'visualization': 'levseq.visualization',
+}
+
+_LAZY_EXPORTS = {
+    'ALL_AAS': 'levseq.variantcaller',
+    'AlignIO': 'levseq.visualization',
+    'CODONS': 'levseq.globals',
+    'CWD': 'levseq.interface',
+    'ColumnDataSource': 'levseq.visualization',
+    'Counter': 'levseq.visualization',
+    'CustomJS': 'levseq.visualization',
+    'DEFAULT_TARGETS': 'levseq.globals',
+    'Div': 'levseq.visualization',
+    'FactorRange': 'levseq.visualization',
+    'HoverTool': 'levseq.visualization',
+    'Label': 'levseq.visualization',
+    'Legend': 'levseq.visualization',
+    'LegendItem': 'levseq.visualization',
+    'Motif': 'levseq.visualization',
+    'MultipleSeqAlignment': 'levseq.visualization',
+    'NUC_COLOR_DICT': 'levseq.visualization',
+    'PCA': 'levseq.user',
+    'Path': 'levseq.variantcaller',
+    'Range1d': 'levseq.visualization',
+    'RangeSlider': 'levseq.visualization',
+    'Rect': 'levseq.visualization',
+    'SCORE_MATRIX': 'levseq.globals',
+    'SW_ALIGN_PARAMS': 'levseq.globals',
+    'SciUtil': 'levseq.user',
+    'Seq': 'levseq.filter_orientation',
+    'SeqIO': 'levseq.variantcaller',
+    'Spacer': 'levseq.visualization',
+    'Tap': 'levseq.visualization',
+    'TapTool': 'levseq.visualization',
+    'Text': 'levseq.visualization',
+    'ThreadPool': 'levseq.variantcaller',
+    'ThreadPoolExecutor': 'levseq.filter_orientation',
+    'VariantCaller': 'levseq.variantcaller',
+    'WELL_IDS': 'levseq.visualization',
+    'aa1': 'levseq.variantcaller',
+    'aa_to_index': 'levseq.user',
+    'aggregate_conservation': 'levseq.visualization',
+    'aggregate_gray_blocks': 'levseq.visualization',
+    'alignment_from_cigar': 'levseq.variantcaller',
+    'amino_acid_to_codon': 'levseq.variantcaller',
+    'amino_acids': 'levseq.user',
+    'annotations': 'levseq.visualization',
+    'argparse': 'levseq.interface',
+    'as_completed': 'levseq.filter_orientation',
+    'basecall_model': 'levseq.interface',
+    'binomtest': 'levseq.variantcaller',
+    'build_cli_parser': 'levseq.interface',
+    'build_kmer_set': 'levseq.filter_orientation',
+    'calc_mutation_significance_for_position_in_well': 'levseq.variantcaller',
+    'calculate_mutation_significance_across_well': 'levseq.variantcaller',
+    'cc': 'levseq.visualization',
+    'check_demultiplexing': 'levseq.variantcaller',
+    'check_variants': 'levseq.simulation',
+    'column': 'levseq.visualization',
+    'combine_pvalues': 'levseq.variantcaller',
+    'combine_seq_func_data': 'levseq.interface',
+    'convert_variant_df_to_seqs': 'levseq.user',
+    'count_kmer_hits': 'levseq.filter_orientation',
+    'deepcopy': 'levseq.variantcaller',
+    'defaultdict': 'levseq.variantcaller',
+    'execute_LevSeq': 'levseq.interface',
+    'figure': 'levseq.visualization',
+    'filter_demultiplexed_folder': 'levseq.filter_orientation',
+    'filter_single_file': 'levseq.filter_orientation',
+    'generate_epcr_library': 'levseq.simulation',
+    'generate_platemaps': 'levseq.visualization',
+    'generate_ssm_library': 'levseq.simulation',
+    'get_colour': 'levseq.user',
+    'get_cons': 'levseq.visualization',
+    'get_cons_diff_colorNseq': 'levseq.visualization',
+    'get_cons_seq': 'levseq.visualization',
+    'get_dummy_plate_df': 'levseq.variantcaller',
+    'get_mut': 'levseq.variantcaller',
+    'get_reads_for_well': 'levseq.variantcaller',
+    'get_sequence_colors': 'levseq.visualization',
+    'get_sequence_diff_colorNseq': 'levseq.visualization',
+    'get_template_df': 'levseq.variantcaller',
+    'get_variant_label_for_well': 'levseq.variantcaller',
+    'get_well_ids': 'levseq.visualization',
+    'glob': 'levseq.variantcaller',
+    'gridplot': 'levseq.visualization',
+    'gzip': 'levseq.filter_orientation',
+    'hv': 'levseq.visualization',
+    'init_notebook_env': 'levseq.visualization',
+    'insert_nt': 'levseq.simulation',
+    'iter_fastq_records': 'levseq.filter_orientation',
+    'logger': 'levseq.variantcaller',
+    'logging': 'levseq.variantcaller',
+    'main': 'levseq.cmd',
+    'make_epcr_de_experiment': 'levseq.simulation',
+    'make_experiment': 'levseq.simulation',
+    'make_mixed_well_epcr_de_experiment': 'levseq.simulation',
+    'make_msa': 'levseq.user',
+    'make_oligopool_plates': 'levseq.visualization',
+    'make_pca': 'levseq.user',
+    'make_row_from_read_pileup_across_well': 'levseq.variantcaller',
+    'make_ssm_de_experiment': 'levseq.simulation',
+    'make_well_df_for_saving': 'levseq.simulation',
+    'make_well_df_from_reads': 'levseq.variantcaller',
+    'match_color': 'levseq.visualization',
+    'math': 'levseq.variantcaller',
+    'min_depth': 'levseq.interface',
+    'mpl': 'levseq.visualization',
+    'multipletests': 'levseq.variantcaller',
+    'mutate_sequence': 'levseq.simulation',
+    'np': 'levseq.variantcaller',
+    'ns': 'levseq.visualization',
+    'one_hot_encode': 'levseq.user',
+    'os': 'levseq.variantcaller',
+    'output_file': 'levseq.visualization',
+    'output_notebook': 'levseq.visualization',
+    'padding_end': 'levseq.interface',
+    'padding_start': 'levseq.interface',
+    'pd': 'levseq.variantcaller',
+    'plot_empty': 'levseq.visualization',
+    'plot_seaborn_heatmap': 'levseq.visualization',
+    'plot_sequence_alignment': 'levseq.visualization',
+    'plt': 'levseq.visualization',
+    'pn': 'levseq.visualization',
+    'postprocess_variant_df': 'levseq.variantcaller',
+    'pysam': 'levseq.variantcaller',
+    'random': 'levseq.variantcaller',
+    're': 'levseq.variantcaller',
+    'row': 'levseq.visualization',
+    'run_LevSeq': 'levseq.interface',
+    'sample_kmer_positions': 'levseq.filter_orientation',
+    'save': 'levseq.visualization',
+    'show': 'levseq.visualization',
+    'shutil': 'levseq.variantcaller',
+    'sns': 'levseq.visualization',
+    'subprocess': 'levseq.variantcaller',
+    'sys': 'levseq.visualization',
+    'threshold': 'levseq.interface',
+    'tqdm': 'levseq.variantcaller',
+    'translate': 'levseq.variantcaller',
+    'u': 'levseq.user',
+    'warnings': 'levseq.variantcaller',
+    'well2nb': 'levseq.visualization',
+    'write_msa_for_df': 'levseq.simulation',
+}
+
+__all__ = [
+    '__title__',
+    '__description__',
+    '__url__',
+    '__version__',
+    '__author__',
+    '__author_email__',
+    '__license__',
+    *sorted(_LAZY_MODULES),
+    *sorted(_LAZY_EXPORTS),
+]
+
+
+def __getattr__(name):
+    if name in _LAZY_MODULES:
+        module = import_module(_LAZY_MODULES[name])
+        vars(_sys.modules[__name__])[name] = module
+        return module
+
+    if name in _LAZY_EXPORTS:
+        module = import_module(_LAZY_EXPORTS[name])
+        value = getattr(module, name)
+        vars(_sys.modules[__name__])[name] = value
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(vars(_sys.modules[__name__])) | set(__all__))

{levseq-1.5 → levseq-1.5.1}/levseq/run_levseq.py

@@ -15,56 +15,24 @@
 #                                                                             #
 ###############################################################################
 
-# Import MinION objects
-from levseq import *
-from levseq.filter_orientation import filter_demultiplexed_folder
-# Import external packages
 import logging
-from pathlib import Path
-import numpy as np
-import pandas as pd
-from importlib import resources
-import subprocess
-from Bio import SeqIO
-import tqdm
-import platform
-import subprocess
 import os
+import platform
 import re
-import gzip
-import shutil
-
-import panel as pn
-import holoviews as hv
-from holoviews.streams import Tap
-import matplotlib
-
-import os
-import logging
-import pandas as pd
-from pathlib import Path
 import shutil
 import subprocess
-from Bio import SeqIO
-import platform
-import numpy as np
-import tqdm
-
-import os
-import logging
-import pandas as pd
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from importlib import resources
 from pathlib import Path
-import shutil
-import subprocess
-from Bio import SeqIO
-import platform
+
 import numpy as np
+import pandas as pd
 import tqdm
-import panel as pn
-import holoviews as hv
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from importlib import resources
-from holoviews.streams import Tap
+from Bio import SeqIO
+
+from levseq.filter_orientation import filter_demultiplexed_folder
+from levseq.utils import translate
+from levseq.variantcaller import VariantCaller
 
 # Utility function to configure logging
 def configure_logging(result_folder, cl_args):
@@ -472,6 +440,8 @@ def save_platemap_to_file(heatmaps, outputdir, name, show_msa):
     if show_msa:
         heatmaps.save(file_path + "_msa.html", embed=True)
     else:
+        import holoviews as hv
+
         hv.renderer("bokeh").save(heatmaps, file_path)
 
 def save_csv(df, outputdir, name):
@@ -721,6 +691,8 @@ def run_LevSeq(cl_args, tqdm_fn=tqdm.tqdm):
         processed_csv = os.path.join(result_folder, "visualization_partial.csv")
         df_vis.to_csv(processed_csv, index=False)
         if cl_args["oligopool"]:
+            from levseq.visualization import make_oligopool_plates
+
             make_oligopool_plates(df_vis, result_folder=result_folder, save_files=True)
     except Exception as e:
         processed_csv = os.path.join(result_folder, "visualization_partial.csv")
@@ -730,6 +702,8 @@ def run_LevSeq(cl_args, tqdm_fn=tqdm.tqdm):
         raise
     
     try:
+        from levseq.visualization import generate_platemaps
+
         layout = generate_platemaps(
             max_combo_data=df_vis,
             result_folder=result_folder,

{levseq-1.5 → levseq-1.5.1/levseq.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: levseq
-Version: 1.5
+Version: 1.5.1
 Home-page: https://github.com/fhalab/levseq/
 Author: Yueming Long, Ariane Mora, Francesca-Zhoufan Li, Emre Gursoy
 Author-email: ylong@caltech.edu
@@ -74,43 +74,78 @@ Figure 1: Overview of the LevSeq variant sequencing workflow using Nanopore tech
 - **Reversed workflow architecture**: LevSeq 2.0 will perform alignment first, then demultiplexing (rather than the current demultiplexing-first approach), resolving issues with forward and reverse read handling
 - **Improved accuracy**: These changes will provide more robust demultiplexing and variant calling across diverse experimental conditions
 
-**Please reach out to us at ylong@caltech.edu if you are planning to order barcoded primers now**
+**If you are planning to order barcoded primers now, or need detailed help with troubleshooting or barcode design, please reach out at [lyming2021@gmail.com](mailto:lyming2021@gmail.com).**
 
 ## Notes
 
-LevSeq was designed for epPCR and SSM experiments, however, we are currently extending it to work for other enzyme engineering designs as well, the current features are under development:
+LevSeq was designed for epPCR and SSM experiments. We are also extending it to support additional enzyme engineering designs. Current features under development include:
 
-1. Insertion handling (see version 4.1.3) - thanks to  Brian Zhong for his contributions to this section!
-2. Gene calling (handling different genes, use the `--oligopool` flag)
+1. Insertion handling (see version 4.1.3). Thanks to Brian Zhong for contributions to this section.
+2. Gene calling for experiments with different genes, using the `--oligopool` flag.
 
-If you notice any issues with new features or have adapted the LevSeq code for your own use cases, we would love community contributions! Please submit either an issue, or a pull request and we will aim to incorperate the changes.
+If you notice issues with new features or have adapted LevSeq for your own use case, community contributions are welcome. Please submit an issue or pull request and we will aim to incorporate the changes.
 
 Performance update: demultiplexing now runs in parallel batches of 8 plates and input FASTQs are staged once per run, improving throughput on multi-core systems.
 
+Recent repository polish:
+- Faster imports: `import levseq` no longer initializes visualization libraries unless they are needed.
+- Cleaner run startup: plotting dependencies are loaded only when platemaps are generated.
+- Packaging cleanup: bundled barcode files and demultiplex binaries are now declared through package discovery.
+- Git hygiene: local `node_modules/` folders are ignored.
+
 ## Quick Start
 
-Note the current stable version is: `1.5`, the latest version is `1.5`. 
+Note the current stable version is: `1.5.1`, the latest version is `1.5.1`.
 
 For stable releases these are made available via docker and pip. For latest versions, please clone the repo and install locally (see *Local development or install of latest version* below).
 
+### How to Run LevSeq
+
+Before running LevSeq, prepare:
+- A folder containing Oxford Nanopore basecalled FASTQ files, usually from a `fastq_pass` directory.
+- A reference CSV file with the columns `barcode_plate`, `name`, and `refseq` (see [Reference File Format](#reference-file-format-refcsv)).
+- A run name, which LevSeq uses as the output folder name.
+
+The basic command format is:
+
+```bash
+levseq <run_name> <path_to_fastq_folder> <path_to_ref_csv>
+```
+
+Example:
+
+```bash
+levseq my_experiment /path/to/fastq_pass /path/to/ref.csv
+```
+
+LevSeq writes results to an output folder named after `<run_name>`. Key outputs include `variants.csv`, `visualization_partial.csv`, result CSV files, logs, and interactive platemap HTML files.
+
+Common run options:
+- Use `--output /path/to/output` to choose where the run folder is created.
+- Use `--skip_demultiplexing` if reads have already been demultiplexed.
+- Use `--skip_variantcalling` if you only want to run demultiplexing.
+- Use `--oligopool` for experiments with multiple genes or references per barcode plate.
+- Use `--show_msa` to include multiple sequence alignment views in the output.
+
 ### Docker Installation (Recommended)
 
 1. Install Docker: [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/)
 2. Pull the appropriate image:
    ```bash
    # For Linux/Windows x86 systems:
-   docker pull yueminglong/levseq:levseq-1.4-x86
+   docker pull yueminglong/levseq:levseq-1.5.1-x86
    
    # For Mac M-series chips (M1, M2, M3, M4):
-   docker pull yueminglong/levseq:levseq-1.4-arm64
+   docker pull yueminglong/levseq:levseq-1.5.1-arm64
    ```
 3. Run LevSeq:
    ```bash
-   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv
+   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv
    ```
+   Replace `levseq-1.5.1-arm64` with the image tag that matches your platform and release.
 4. Connect function data to your sequence data
    ```bash
-   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv --fitness_files "levseq_results/20250712_epPCR_Q06714_37.csv,levseq_results/20250712_epPCR_Q06714_39.csv,levseq_results/20250712_epPCR_Q06714_40.csv" --smiles 'O=P(OC1=CC=CC=C1)(OC2=CC=CC=C2)OC3=CC=CC=C3>>O=P(O)(OC4=CC=CC=C4)OC5=CC=CC=C5' --compound dPPi --variant_df "levseq_results/visualization_partial.csv"
+   docker run --rm -v "/full/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv --fitness_files "levseq_results/20250712_epPCR_Q06714_37.csv,levseq_results/20250712_epPCR_Q06714_39.csv,levseq_results/20250712_epPCR_Q06714_40.csv" --smiles 'O=P(OC1=CC=CC=C1)(OC2=CC=CC=C2)OC3=CC=CC=C3>>O=P(O)(OC4=CC=CC=C4)OC5=CC=CC=C5' --compound dPPi --variant_df "levseq_results/visualization_partial.csv"
    ```
 ### Pip Installation (Mac/Linux only)
 
@@ -145,11 +180,11 @@ brew install gcc@13 gcc@14
    levseq my_experiment /path/to/data/ /path/to/ref.csv  "LCMS_file_{barcode1}.csv,LCMS_file_{barcode2}.csv," --smiles 'reaction_smiles_string' --compound "name_of_compound_in_LCMS_file" --variant_df "visualization_partial.csv"
    ```
 
-Note for function data we currently expect a LCMS file e.g. with the columns: 
+For function data, LevSeq currently expects LCMS files with these columns:
 - `Sample Vial Number` (corresponding to the well that the sample was from). 
 - `Area` (which becomes fitness value). 
 - `Compound Name` which is the name of the compound we filter for that is passed as a parameter.
-- The last `_X.csv` needs to be the barcode number to match that sample to your plate e.g. if you ran LevSeq with barcode 33 for plate 2 you need to have `_33.csv` for the fitness file for plate 2. e.g. `some_fitnes_for_plate_2_33.csv`.
+- The final `_X.csv` suffix should contain the barcode number used to match that sample to the correct plate. For example, if plate 2 used barcode 33, the fitness file should end in `_33.csv`, such as `some_fitness_for_plate_2_33.csv`.
 
 
 ## Data and Visualization
@@ -188,6 +223,10 @@ For oligopool experiments (multiple proteins per plate), use:
 - `--output`: Custom save location (defaults to current directory)
 - `--show_msa`: Show multiple sequence alignment for each well
 - `--oligopool`: Process data as oligopool experiment
+- `--fitness_files`: Comma-separated LCMS or function-data CSV files to join with sequence results
+- `--smiles`: Reaction SMILES string used when joining function data
+- `--compound`: Compound name to filter in the function-data files
+- `--variant_df`: LevSeq variant dataframe to join with function data, usually `visualization_partial.csv`
 
 ## Step-by-Step Tutorial
 
@@ -198,7 +237,7 @@ For oligopool experiments (multiple proteins per plate), use:
 2. **Run LevSeq**:
    ```bash
    # Via Docker
-   docker run --rm -v "/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.4-arm64 my_experiment levseq_results/ levseq_results/ref.csv
+   docker run --rm -v "/path/to/data:/levseq_results" yueminglong/levseq:levseq-1.5.1-arm64 my_experiment levseq_results/ levseq_results/ref.csv
    
    # Via pip
    levseq my_experiment /path/to/data/ /path/to/ref.csv
@@ -229,7 +268,7 @@ conda create --name levseq python=3.10
 git clone git@github.com:fhalab/LevSeq.git
 cd LevSeq
 python setup.py sdist bdist_wheel
-pip install dist/levseq-1.4.3.tar.gz
+pip install dist/levseq-1.5.1.tar.gz
 ```
 
 ## Citing LevSeq
@@ -248,4 +287,4 @@ If you find LevSeq useful, please cite our paper:
 
 ## Contact
 
-Leave a feature request in the issues or reach us via [email](mailto:levseqdb@gmail.com).
+For detailed questions, troubleshooting, barcode design support, or feature requests, email [lyming2021@gmail.com](mailto:lyming2021@gmail.com). Reproducible bugs and public feature discussions are also welcome as GitHub issues.

{levseq-1.5 → levseq-1.5.1}/setup.py

@@ -77,13 +77,13 @@ setup(name='levseq',
           'Topic :: Scientific/Engineering :: Bio-Informatics',
       ],
       keywords=['Nanopore', 'ONT', 'evSeq'],
-      packages=['levseq'],
+      packages=find_packages(exclude=['tests', 'tests.*']),
       include_package_data=True,
       package_data={
           'levseq.barcoding': [
               'minion_barcodes.fasta',
               'demultiplex',
-              'demultiplex-arm64'
+              'demultiplex-arm64',
               'demultiplex-x86',
           ],
       },

levseq-1.5/levseq/__init__.py

@@ -1,34 +0,0 @@
-###############################################################################
-#                                                                             #
-#    This program is free software: you can redistribute it and/or modify     #
-#    it under the terms of the GNU General Public License as published by     #
-#    the Free Software Foundation, either version 3 of the License, or        #
-#    (at your option) any later version.                                      #
-#                                                                             #
-#    This program is distributed in the hope that it will be useful,          #
-#    but WITHOUT ANY WARRANTY; without even the implied warranty of           #
-#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            #
-#    GNU General Public License for more details.                             #
-#                                                                             #
-#    You should have received a copy of the GNU General Public License        #
-#    along with this program. If not, see <http://www.gnu.org/licenses/>.     #
-#                                                                             #
-###############################################################################
-
-__title__ = 'levseq'
-__description__ = 'LevSeq nanopore sequencing'
-__url__ = 'https://github.com/fhalab/levseq/'
-__version__ = '1.5'
-__author__ = 'Yueming Long, Ariane Mora, Francesca-Zhoufan Li, Emre Gursoy'
-__author_email__ = 'ylong@caltech.edu'
-__license__ = 'GPL3'
-
-from levseq.globals import *
-from levseq.variantcaller import *
-from levseq.visualization import *
-from levseq.interface import *
-from levseq.cmd import *
-from levseq.utils import *
-from levseq.simulation import *
-from levseq.user import *
-from levseq.filter_orientation import *