Applying Code Standards

Applying Code Standards

Review checklist for ensuring analysis code meets quality standards for maintainability and reproducibility. Covers project structure, readability, reproducibility, and documentation.

---

Required Output Files (MANDATORY)

Your analysis MUST include these files. Do not consider the analysis complete without them:

1. config.py - All parameters with rationale comments explaining each threshold
2. requirements.txt - Pinned dependency versions (e.g., pandas==2.0.3)
3. README.md - Setup and usage instructions

---

Checklist

Copy this checklist and track progress:

Code Quality Review:
- [ ] Project structure
- [ ] Readability
- [ ] No unnecessary duplication
- [ ] Configuration is explicit
- [ ] Inputs are validated
- [ ] Reproducibility
- [ ] Documentation
- [ ] Housekeeping

---

Guidelines

1. Project Structure

• ALWAYS maintain a clean, consistent directory layout
• Separate exploratory work (notebooks, helper scripts) from production code (modules)
• Treat raw data as immutable — never overwrite originals
• ALWAYS create requirements.txt with the python version (echo "# "$(python --version) >> requirements.txt) and pinned versions (pip freeze >> requirements.txt) to capture the software environment for reproducibility.

Required: requirements.txt example:

# Python 3.13.2
pandas==2.0.3
numpy==1.24.0

2. Readability

• A program should not require readers to hold more than a handful of facts in memory at once
• Make names consistent, distinctive, and meaningful (functions, variables, files)
• Make code style and formatting consistent
• Keep functions small and focused — each should do one thing well
• Do not comment and uncomment sections of code to control behavior; use configuration instead
• Avoid hardcoded paths: use pathlib and relative paths or environment variables
• Keep data loading, processing, analysis, and visualization in distinct stages

3. No Unnecessary Duplication

• Every piece of data must have a single authoritative representation
• Modularize code rather than copying and pasting
• Re-use well-maintained libraries instead of reimplementing common functionality
• Prefer a little duplication over the wrong abstraction — do not over-engineer

4. Explicit Configuration (REQUIRED)

• ALWAYS define experimental parameters (thresholds, hyperparameters) as named constants in one place
• ALWAYS document the rationale for cutoffs and thresholds near their definitions
• ALWAYS separate configuration from code using a config file

Required: config.py example with rationale:

# Analysis Configuration

# FDR threshold for multiple testing correction
# Rationale: Standard proteomics threshold balancing discovery vs false positives
FDR_THRESHOLD = ...

# Minimum valid values required per group for statistical testing
# Rationale: At least ... values needed for variance estimation
MIN_VALID_VALUES = ...

5. Input Validation

• Validate inputs early using assertions or schema libraries (pandera, pydantic)
• Add assertions at key checkpoints to verify intermediate results
• Fail fast and loudly — silent failures hide bugs

6. Reproducibility

• ALWAYS set random seeds explicitly via named variables in config
• ALWAYS record the software environment in requirements.txt
• Automate the full pipeline so results can be regenerated from raw data following a linear analysis path
• Log or save key parameters and metadata alongside outputs

7. Documentation

• Aim for self-explanatory code; reserve comments for why, not what
• ALWAYS add type hints for ALL function signatures
• Place a brief docstring at the top of every module explaining its purpose
• ALWAYS include a README.md explaining setup and how to run the analysis

Required: Type hints for all functions:

def divide(enumerator: float, divisor: float) -> float:
    """Divide enumerator by divisor"""
    return  enumerator/divisor

Required: README.md template:

# Analysis: [Name]

## Overview
Brief description of the analysis purpose.

## Setup
```bash
pip install -r requirements.txt

Usage

python main.py

Input

• data/input_file.txt - Description of input data

Output

• output/results.csv - Description of output

Configuration

Parameters can be modified in config.py.

### 8. Housekeeping

- Remove unused code, temporary files, and dead notebooks at the end

---

## Pre-Submission Checklist (MANDATORY)

Before finalizing your analysis, verify ALL of these exist:

- [ ] **`config.py`** exists with ALL thresholds and rationale comments
- [ ] **`requirements.txt`** exists with pinned versions (e.g., `pandas==2.0.3`)
- [ ] **`README.md`** exists with setup/usage/input/output sections
- [ ] All functions have type hints (e.g., `def func(x: int) -> str:`)

If any item is unchecked, go back and add it before completing the analysis.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MannLabs](https://github.com/MannLabs)
- **Source:** [MannLabs/proteomics-agent-skills](https://github.com/MannLabs/proteomics-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.