Metadata-Version: 2.5
Name: wellshuffled
Version: 0.2.0
Summary: A command line utility for shuffling biological sample positions in microwell plates.
Project-URL: Homepage, https://github.com/exfab/wellshuffled
Project-URL: Repository, https://github.com/exfab/wellshuffled.git
Project-URL: Issues, https://github.com/exfab/wellshuffled/issues
Author-email: Andrew McNaughton <mcnaughtonadm@gmail.com>
Maintainer-email: Andrew McNaughton <mcnaughtonadm@gmail.com>
License: MIT License
License-File: LICENSE
Keywords: microwell plate,plate randomization
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: click>=8.3.0
Requires-Dist: numpy>=2.3.3
Description-Content-Type: text/markdown

# WellShuffled 🎲

---

## Quickstart

1.  Create a simple `samples.txt` file:

    ```bash
    echo -e "SampleA\nSampleB\nSampleC\nSampleD" > samples.txt
    ```

2.  Run `wellshuffled` using `uvx` to instantly generate a plate map:

    ```bash
    uvx wellshuffled shuffle samples.txt my_first_plate.csv
    ```

3.  View your new plate map!
    ```bash
    cat my_first_plate.csv
    ```

---

## Installation

There are two ways to install `wellshuffled`:

**Option 1: Install using `uv` or `pip`**

You can install the latest version of `wellshuffled` by running the following
commands:

1. **Using `uv`:**

```
uv pip install wellshuffled
```

2. **Using `pip`:**

```
pip install wellshuffled
```

**Option 2: Install from a local clone**

1.  **Clone the repository:**

    ```
    git clone https://github.com/exfab/wellshuffled.git
    cd wellshuffled
    ```

2.  **Install using `pip`:**

    ```
    pip install .
    ```

---

## Usage

The main command is `wellshuffled`. It has two subcommands: `shuffle` and
`trace`.

After installation, you can run the tool from your terminal like this:

```
wellshuffled --help
```

### `shuffle` Command

The `shuffle` command generates randomized plate maps from a list of sample IDs.

```
wellshuffled shuffle <sample_file> <output_path> [OPTIONS]
```

**Options:**

- `--plates, -n`: Number of plates to generate. Default is 1.
- `--size`: Well plate size (96 or 384). Default is 96.
- `--simple`: Use simple randomization (disables neighbor-awareness).
- `--separate-files`: Save each plate map to a separate CSV file.
- `--seed`: Set the random seed for reproducible results.
- `--control-prefix`: Prefix used to identify control samples.
- `--fixed-map`: Manually specify fixed control locations (e.g.,
  "A1:control-85,H12:control-96").
- `--fixed-map-file`: Manually specify fixed control locations from a CSV file.
- `--nonstandard`: Allow for the use of non-standard plate dimensions.
- `--nonstandard_dims`: The dimensions (x, y) for the nonstandard plate.

Plates with more than 26 rows are supported, and follow the convention used by
1536-well plates: rows are labelled `A` through `Z`, then continue with multiple
letters, so row 27 is `AA`, row 28 is `AB`, and so on. For example, a 1536-well
plate is given as `--nonstandard_dims 32,48`, and its wells are labelled from
`A1` through `AF48`.

### `trace` Command

The `trace` command traces the locations of samples across multiple plates.

```
wellshuffled trace <input_path> [OPTIONS]
```

**Options:**

- `--output-csv`: Optional path to save the full trajectory map as a CSV file.
- `--numeric`: Return the plate positions as 1-based column major numeric
  values.

### Examples

_Note: The following examples assume you have cloned the repository and are
running the commands from the project's root directory._

**1. Generate a single 96-well plate with neighbor-awareness:**

```
wellshuffled shuffle example_files/samples.csv single_plate.csv --size 96
```

**2. Generate 5 plates and save to a single combined file:**

```
wellshuffled shuffle example_files/samples.csv combined_layouts.csv --plates 5
```

**3. Generate 3 plates and save them to separate files in a directory:** The
output path `my_layouts` will be created if it doesn't exist.

```
wellshuffled shuffle example_files/samples.csv my_layouts --plates 3 --separate-files
```

**4. Generate a reproducible layout using a seed:** Running this command
multiple times with `--seed 123` will always produce the exact same output file.

```
wellshuffled shuffle example_files/samples.csv reproducible_run.csv --plates 4 --seed 123
```

**5. Use the simple randomization logic (disabling neighbor-awareness):**

```
wellshuffled shuffle example_files/samples.csv simple_run.csv --simple
```

**6. Generate a plate with a predefined layout for the first plate:** The
`samples_with_positions.csv` file contains a second column with the initial well
positions.

```
wellshuffled shuffle example_files/samples_with_positions.csv predefined_layout.csv
```

**7. Provide Nonstandard plate dimensions:** We use the `--nonstandard` flag to
ensure you are explicitly meaning to pass in nonstandard plate dimensions along
with the `--nonstandard_dims=[RowsxColumns] or [Rows,Columns]`

```
wellshuffled shuffle example_files/60_samples_w_controls_initial_pos.csv nonstandard_layout.csv --nonstandard --nonstandard_dims=6,10
```

**8. View all available options and help:**

```
wellshuffled --help
```

## Development Installation

If you want to contribute to the development of `wellshuffled`, you can set up a
development environment by following these steps:

1.  **Clone the repository:**

    ```
    git clone https://github.com/exfab/wellshuffled.git
    cd wellshuffled
    ```

2.  **Sync the project using `uv`:**

    This project is managed with `uv`, a fast Python package installer and
    resolver.

    ```
    uv sync
    ```

3.  **Installing without `uv sync` or using `venv`**

    If you encounter errors with `uv sync`, you can install the project manually
    in editable mode:

    Using `uv`:

    ```
    uv run python -m pip install -e .
    ```

    Using `venv`:

    ```
    python -m venv .venv
    source .venv/bin/activate
    python -m pip install -e .
    ```
