| Name | ee-metadata JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | A high-performance CLI tool from eDNA-Explorer to generate metadata from a directory of fastq files. |
| upload_time | 2025-08-05 00:27:02 |
| maintainer | None |
| docs_url | None |
| author | Jim Jeffers |
| requires_python | <4.0,>=3.9 |
| license | MIT |
| keywords |
bioinformatics
fastq
metadata
genomics
cli
edna
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# ee-metadata
A high-performance, command-line tool from eDNA-Explorer to scan a directory of .fastq.gz files, identify primer sequences, pair forward and reverse reads, and generate a metadata CSV file. Built with Polars for maximum speed and efficiency.
## Features
- **Fast Analysis**: Leverages the Polars DataFrame library for rapid processing of primer and metadata files.
- **Primer Detection**: Scans the beginning of each FASTQ file to detect known forward and reverse primer sequences.
- **Intelligent Pairing**: Pairs forward (R1) and reverse (R2) read files based on common naming conventions.
- **Flexible & Robust**: Handles ambiguous IUPAC codes in primer sequences and provides options for forcing file pairs.
- **User-Friendly CLI**: Clean, documented command-line interface powered by Typer, with rich terminal output.
## Installation
### Quick Install with uv or pipx (Recommended)
The easiest way to install `ee-metadata` is using `uv` or `pipx`, which will install it as a standalone CLI tool:
**Using uv (fastest):**
```bash
uv tool install ee-metadata
```
**Using pipx:**
```bash
pipx install ee-metadata
```
After installation, you can run the tool directly:
```bash
ee-metadata --help
```
### Install from PyPI with pip
```bash
pip install ee-metadata
```
### Development Installation
For development or if you prefer Poetry:
#### 1. Install Poetry
Follow the official instructions: [Poetry Installation Guide](https://python-poetry.org/docs/#installation).
#### 2. Clone the Repository
```bash
git clone https://github.com/eDNA-Explorer/ee-metadata.git
cd ee-metadata
```
#### 3. Install Dependencies
```bash
poetry install
```
#### 4. Run with Poetry
```bash
poetry run ee-metadata
```
### 4. Enable Tab Completion (Optional)
To enable tab completion for file paths and options, install shell completion:
**For Bash:**
```bash
poetry run ee-metadata --install-completion bash
```
**For Zsh:**
```bash
poetry run ee-metadata --install-completion zsh
```
**For Fish:**
```bash
poetry run ee-metadata --install-completion fish
```
## Usage
Once installed, you can run the tool using poetry run.
### Command
```bash
poetry run ee-metadata [OPTIONS] [INPUT_DIR]
```
### Arguments
- **INPUT_DIR**: (Optional) The path to the directory containing your .fastq.gz files. If not provided, you'll be prompted to enter it interactively.
### Options
| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--primers` | `-p` | (Required) Path to the primers CSV file. | - |
| `--output` | `-o` | Path for the output metadata CSV file. | `metadata.csv` |
| `--num-records` | `-n` | Number of records to scan in each FASTQ file for primer detection. | `100` |
| `--force-pairing` | | Force pairing of files based on common base names if primer analysis fails. | `False` |
| `--help` | | Show the help message and exit. | - |
### Examples
**Interactive mode (prompts for input directory):**
```bash
poetry run ee-metadata
```
**With directory specified (supports tab completion):**
```bash
# Use tab completion to autocomplete paths
poetry run ee-metadata <TAB> # Press tab to see available directories
# Analyze FASTQ files in the 'data/raw_reads' directory using default primers
poetry run ee-metadata ./data/raw_reads
# Analyze FASTQ files with custom primers and output file (use tab completion)
poetry run ee-metadata ./data/raw_reads --primers <TAB> --output <TAB>
```
## Contributing
Contributions are welcome! Please feel free to submit a pull request or open an issue for bugs, feature requests, or questions.
Raw data
{
"_id": null,
"home_page": null,
"name": "ee-metadata",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "bioinformatics, fastq, metadata, genomics, cli, edna",
"author": "Jim Jeffers",
"author_email": "jim@ednaexplorer.org",
"download_url": "https://files.pythonhosted.org/packages/c7/47/8851507efee193ed88aeec34c64d7443456143b5550a867abd9d09c16412/ee_metadata-0.2.2.tar.gz",
"platform": null,
"description": "# ee-metadata\n\nA high-performance, command-line tool from eDNA-Explorer to scan a directory of .fastq.gz files, identify primer sequences, pair forward and reverse reads, and generate a metadata CSV file. Built with Polars for maximum speed and efficiency.\n\n## Features\n\n- **Fast Analysis**: Leverages the Polars DataFrame library for rapid processing of primer and metadata files.\n- **Primer Detection**: Scans the beginning of each FASTQ file to detect known forward and reverse primer sequences.\n- **Intelligent Pairing**: Pairs forward (R1) and reverse (R2) read files based on common naming conventions.\n- **Flexible & Robust**: Handles ambiguous IUPAC codes in primer sequences and provides options for forcing file pairs.\n- **User-Friendly CLI**: Clean, documented command-line interface powered by Typer, with rich terminal output.\n\n## Installation\n\n### Quick Install with uv or pipx (Recommended)\n\nThe easiest way to install `ee-metadata` is using `uv` or `pipx`, which will install it as a standalone CLI tool:\n\n**Using uv (fastest):**\n```bash\nuv tool install ee-metadata\n```\n\n**Using pipx:**\n```bash\npipx install ee-metadata\n```\n\nAfter installation, you can run the tool directly:\n```bash\nee-metadata --help\n```\n\n### Install from PyPI with pip\n\n```bash\npip install ee-metadata\n```\n\n### Development Installation\n\nFor development or if you prefer Poetry:\n\n#### 1. Install Poetry\nFollow the official instructions: [Poetry Installation Guide](https://python-poetry.org/docs/#installation).\n\n#### 2. Clone the Repository\n```bash\ngit clone https://github.com/eDNA-Explorer/ee-metadata.git\ncd ee-metadata\n```\n\n#### 3. Install Dependencies\n```bash\npoetry install\n```\n\n#### 4. Run with Poetry\n```bash\npoetry run ee-metadata\n```\n\n### 4. Enable Tab Completion (Optional)\nTo enable tab completion for file paths and options, install shell completion:\n\n**For Bash:**\n```bash\npoetry run ee-metadata --install-completion bash\n```\n\n**For Zsh:**\n```bash\npoetry run ee-metadata --install-completion zsh\n```\n\n**For Fish:**\n```bash\npoetry run ee-metadata --install-completion fish\n```\n\n## Usage\n\nOnce installed, you can run the tool using poetry run.\n\n### Command\n```bash\npoetry run ee-metadata [OPTIONS] [INPUT_DIR]\n```\n\n### Arguments\n- **INPUT_DIR**: (Optional) The path to the directory containing your .fastq.gz files. If not provided, you'll be prompted to enter it interactively.\n\n### Options\n\n| Option | Alias | Description | Default |\n|--------|-------|-------------|---------|\n| `--primers` | `-p` | (Required) Path to the primers CSV file. | - |\n| `--output` | `-o` | Path for the output metadata CSV file. | `metadata.csv` |\n| `--num-records` | `-n` | Number of records to scan in each FASTQ file for primer detection. | `100` |\n| `--force-pairing` | | Force pairing of files based on common base names if primer analysis fails. | `False` |\n| `--help` | | Show the help message and exit. | - |\n\n### Examples\n\n**Interactive mode (prompts for input directory):**\n```bash\npoetry run ee-metadata\n```\n\n**With directory specified (supports tab completion):**\n```bash\n# Use tab completion to autocomplete paths\npoetry run ee-metadata <TAB> # Press tab to see available directories\n\n# Analyze FASTQ files in the 'data/raw_reads' directory using default primers\npoetry run ee-metadata ./data/raw_reads\n\n# Analyze FASTQ files with custom primers and output file (use tab completion)\npoetry run ee-metadata ./data/raw_reads --primers <TAB> --output <TAB>\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a pull request or open an issue for bugs, feature requests, or questions.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A high-performance CLI tool from eDNA-Explorer to generate metadata from a directory of fastq files.",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/eDNA-Explorer/ee-metadata",
"Repository": "https://github.com/eDNA-Explorer/ee-metadata"
},
"split_keywords": [
"bioinformatics",
" fastq",
" metadata",
" genomics",
" cli",
" edna"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6666bcb52468e80e2c7202ccf9a6ca935144acfe9bfc54272de05665054b0beb",
"md5": "745e9efcfd2c81e539dc410fdbf974a0",
"sha256": "8cd0505500cedcd1aa9f388394860ba4e544029cb47bae87a789e4782ab2fe78"
},
"downloads": -1,
"filename": "ee_metadata-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "745e9efcfd2c81e539dc410fdbf974a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 25497,
"upload_time": "2025-08-05T00:27:01",
"upload_time_iso_8601": "2025-08-05T00:27:01.057934Z",
"url": "https://files.pythonhosted.org/packages/66/66/bcb52468e80e2c7202ccf9a6ca935144acfe9bfc54272de05665054b0beb/ee_metadata-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c7478851507efee193ed88aeec34c64d7443456143b5550a867abd9d09c16412",
"md5": "9cf71b30398fcbff81216e03dd692df5",
"sha256": "b242e8811ef3b1d649a628a30d1415c14dc36b52ab77af06514c96010f5ab2fd"
},
"downloads": -1,
"filename": "ee_metadata-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "9cf71b30398fcbff81216e03dd692df5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 26951,
"upload_time": "2025-08-05T00:27:02",
"upload_time_iso_8601": "2025-08-05T00:27:02.144358Z",
"url": "https://files.pythonhosted.org/packages/c7/47/8851507efee193ed88aeec34c64d7443456143b5550a867abd9d09c16412/ee_metadata-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 00:27:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eDNA-Explorer",
"github_project": "ee-metadata",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ee-metadata"
}
