Metadata-Version: 2.5
Name: amplifyp
Version: 1.25.1
Summary: Modern Python rewrite of Amplify4 for PCR simulation, amplicon prediction, and primer dimer analysis
Project-URL: Homepage, https://github.com/fangfufu/AmplifyP
Project-URL: Issues, https://github.com/fangfufu/AmplifyP/issues
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: flet==1.0.3
Requires-Dist: pyyaml==6.0.3
Provides-Extra: dev
Requires-Dist: flet-cli==1.0.3; extra == 'dev'
Requires-Dist: prek==0.5.5; extra == 'dev'
Requires-Dist: pyright==1.1.414; extra == 'dev'
Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
Requires-Dist: pytest-playwright==0.9.0; extra == 'dev'
Requires-Dist: pytest-testmon==2.2.0; extra == 'dev'
Requires-Dist: pytest==9.1.1; extra == 'dev'
Provides-Extra: e2e
Requires-Dist: pillow==12.3.0; extra == 'e2e'
Requires-Dist: pytesseract==0.3.13; extra == 'e2e'
Requires-Dist: pytest-playwright==0.9.0; extra == 'e2e'
Requires-Dist: requests==2.34.2; extra == 'e2e'
Description-Content-Type: text/markdown

# AmplifyP

AmplifyP is a open source cross-platform program for simulating and testing
polymerase chain reactions (PCRs). It can be used as a tool for designing
primers by evaluating candidates. It is useful for planning experiments as well
as for teaching students about PCR.

To use AmplifyP, you supply the DNA sequences of one or more primers plus a
length of target DNA sequence, and AmplifyP will generate a map of the expected
outcome. It will also provide other helpful information such as the sequences of
likely amplified fragments, warnings about potential primer dimers, etc.

AmplifyP is a Python rewrite of William Engels's Amplify 4. For a short history
of Amplify, please refer to the [history](docs/history.md) document.

AmplifyP can be used as a graphical user interface (GUI) application (with some
screenshots below), however it is written with programmers in mind. The GUI is
composed on top of the underlying PCR calculation code, which can be easily
accessed programmatically.

<table>
  <tr>
    <td width="33%" align="center">
      <b>Template & Primer Management</b>
    </td>
    <td width="33%" align="center">
      <b>Primer Binding Site & Amplicon</b>
    </td>
    <td width="33%" align="center">
      <b>Primer Dimer Analysis</b>
    </td>
  </tr>
  <tr>
    <td width="33%" align="center">
      <img src="docs/gui/images/input_view.png" alt="Input View" width="100%">
    </td>
    <td width="33%" align="center">
      <img src="docs/gui/images/pcr_view.png" alt="PCR Results View" width="100%">
    </td>
    <td width="33%" align="center">
      <img src="docs/gui/images/primer_dimer_view.png" alt="Primer Dimer Analysis" width="100%">
    </td>
  </tr>
</table>

AmplifyP is available on Linux, Windows and macOS, as well as a web application
and as a package on PyPI.

## Quick start

### Web version

The easiest way to run AmplifyP is to use the web version. The current stable
version of AmplifyP is deployed as a static GitHub Pages site:

- **[AmplifyP Web Version](https://fangfufu.github.io/AmplifyP/)**

### PyPI package

AmplifyP is available on PyPI as
[`amplifyp`](https://pypi.org/project/amplifyp/):

- **[AmplifyP on PyPI](https://pypi.org/project/amplifyp/)**

To install AmplifyP with `pipx`:

```bash
pipx install amplifyp
```

To launch the desktop version, run:

```bash
amplifyp
```

To launch the web version in a browser, run:

```bash
amplifyp --web
```

### Binary releases

The binary releases of AmplifyP are available at the GitHub releases page:

- **[AmplifyP Binary Releases](https://github.com/fangfufu/AmplifyP/releases)**

For **Linux**, you can either download the AppImage or download the tarball.
Both versions are pretty much the same. Some people prefer the AppImage as it is
a single binary. However, please note that certain security settings can prevent
AppImages from running.

For **Windows**, you can either download the ZIP file, or the installer. Both
versions are pretty much the same. To use AmplifyP, it does not actually need to
be installed. However if you run the installer, it would set up shortcuts for
you.

For **macOS**, you can download the DMG file. Please note that I am not a
certified Apple Developer, so there will be security warnings. The Mac binary is
generated by GitHub workflow. I do not actually have access to a Mac, so I
cannot guarantee that the DMG file and the binary inside actually works. The
binary generated should be a universal binary.

The **web** version is for running AmplifyP on your local web server. AmplifyP
web version runs purely on client-side, no computation is done on the server
itself. However you do actually need to run a static web server and access
AmplifyP via the web server. This is due to browser security restriction.

## Graphical User Interface (GUI) Manual

The full user manual for AmplifyP is available **[here](docs/gui/README.md)**.

I tried to make AmplifyP's GUI intuitive. If you are using AmplifyP for checking
existing primers against a DNA template, hopefully you don't need a user manual.

However if you plan to use AmplifyP to design primers using Designer 1D and
Designer 2D, you probably want to read the user manual.

### Short tutorial on PCR simulation and Primer Dimer checking

When you load the program, the Input View is loaded. You paste in the DNA
template on the left-hand side, then you put primers in the table on the right
hand side. You then tick the primer that you want to be enabled.

To run PCR simulation, simply click the PCR view at the button bar at the top.
To check for primer dimers for the enabled primers, click on the Dimer button.

### Primer list: highlighting vs enabling

If you want to highlight a primer or drag it around, click its drag/highlight
handle. This controls which primers are copied or dragged around.

The "Copy" button above the primer list works for primers which have been
highlighted.

Highlighting is different to enabling / disabling primers for PCR simulation and
primer dimer analysis. This distinction was made because some users said they
want to be able to highlight the primers in addition to enable and disable them,
as this helps them with experiment design.

You can quickly highlight a range of entries in the primer list. If you double
click the drag handle of one primer, and double click the drag handle of another
primer, the highlight status of the primers between them (including the primers
that you double clicked on) will be *toggled*, that means if they were not
highlighted, they will be highlighted now.

## Running AmplifyP from the source code repository

If you don't want to run the pre-built binaries, you can run AmplifyP from the
source repository. AmplifyP requires **Python 3.12** or higher.

To run AmplifyP from the source repository, you need to follow these steps:

1. Clone the repository and navigate to the directory:

   ```bash
   git clone https://github.com/fangfufu/AmplifyP.git
   cd AmplifyP
   ```

2. Set up the virtual environment:

   **Debian GNU/Linux**: This was verified under Debian GNU/Linux 13 (trixie), I
   make no guarantee that it works in other Debian derived distributions.

> [!NOTE]
> Note that this also sets up your machine for developing AmplifyP. If you don't
> want that, follow the \*nix instructions.

```bash
./scripts/setup_linux.sh --system-deps
source .venv/bin/activate
```

**\*nix, including GNU/Linux distributions, FreeBSD and macOS**:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install .
```

**Windows**:

```cmd
python -m venv .venv
.venv\Scripts\activate
pip install .
```

If you want to do development on AmplifyP, please refer to the
[Developers' and Contributors' Guide](src/README.md)

## AmplifyP API

It is possible to perform PCR simulation by directly calling AmplifyP's API,
bypassing the GUI. If you have a lot of primers and/or a lot of templates, you
may wish to write a script or a program to go through them, rather than having
to click through the GUI. Install the package with `pip install amplifyp` to get
started. Below is some example code.

```python
from amplifyp.dna import DNA, Primer, DNAType
from amplifyp.pcr import PCR

# Template contains the forward primer at its 5' end and the reverse
# complement of the reverse primer downstream, so one 92 bp amplicon
# is predicted.
template = DNA(
    "CGACTGGGCAAAGGAAATCC"
    "ATGCATGCATGCATGCATGCATGCATGCATGCATGCATGCATGCATGCATGC"
    "CCCAAATTTGTGATACCCAC",
    DNAType.LINEAR,
    name="Template",
)
primer_fwd = Primer("CGACTGGGCAAAGGAAATCC", name="FwdPrimer")
primer_rev = Primer("GTGGGTATCACAAATTTGGG", name="RevPrimer")

pcr = PCR(template)
pcr.add_primer(primer_fwd)
pcr.add_primer(primer_rev)
pcr.predict_amplicons()

for amplicon in pcr.amplicons:
    print(
        f"Product length: {len(amplicon.product)} bp, Q-score: {amplicon.q_score:.2f}"
    )
```

For the full guide on using AmplifyP API, please refer to the
[Python API Guide](docs/api_guide.md)

## Further Readings

For more documentation, please refer to:

- **[Amplify History](docs/history.md)**: A brief history of the Amplify
  software series.
- **[GUI Manual](docs/gui/README.md)**: A detailed manual for running
  simulations, primer management, and configuration in the graphical
  application.
- **[Python API Guide](docs/api_guide.md)**: A developer guide with code
  snippets demonstrating programmatic PCR simulation, dimer analyses, and Tm
  calculations.
- **[Development Guide](src/README.md)**: Information on setting up development
  dependencies, linters, hot-reload, and Pyodide web builds.
- **[Windows Setup Guide](docs/windows_setup.md)**: A step-by-step developer
  guide for setting up the environment, running tests, and compiling installers
  on Windows.

## Attribution

- **William Engels (Amplify4)**: This project is based on
  [Amplify4](https://github.com/wrengels/Amplify4).
- **Roboto Mono Font**: Licenced under the SIL Open Font License, Version 1.1.
  Copyright 2015 The Roboto Mono Project Authors.

## Licence

This project is licensed under the GPL-3.0 Licence. See the [LICENSE](LICENSE)
file for details.
