scientific-writer 2.2.1__py3-none-any.whl → 2.2.3__py3-none-any.whl

scientific_writer/.claude/skills/hypothesis-generation/assets/hypothesis_output_template.md

@@ -0,0 +1,302 @@
+# Scientific Hypothesis Generation: [Phenomenon Name]
+
+## 1. Background & Context
+
+### Phenomenon Description
+[Clear description of the observation, pattern, or question that requires explanation. Include:
+- What was observed or what question needs answering
+- The specific context or system in which it occurs
+- Any relevant constraints or boundary conditions
+- Why this phenomenon is interesting or important]
+
+### Current Understanding
+[Synthesis of existing literature, including:
+- What is already known about this phenomenon
+- Established mechanisms or theories that may be relevant
+- Key findings from recent research
+- Gaps or limitations in current understanding
+- Conflicting findings or unresolved debates
+
+Include citations to key papers (Author et al., Year, Journal)]
+
+### Knowledge Gaps
+[Specific aspects that remain unexplained or poorly understood:
+- What aspects of the phenomenon lack clear explanation?
+- What contradictions exist in current understanding?
+- What questions remain unanswered?]
+
+---
+
+## 2. Competing Hypotheses
+
+### Hypothesis 1: [Concise Title]
+
+**Mechanistic Explanation:**
+[Detailed explanation of the proposed mechanism. This should explain HOW and WHY the phenomenon occurs, not just describe WHAT occurs. Include:
+- Specific molecular, cellular, physiological, or population-level mechanisms
+- Causal chain from initial trigger to observed outcome
+- Key components, pathways, or factors involved
+- Scale or level of explanation (molecular, cellular, organ, organism, population)]
+
+**Supporting Evidence:**
+[Evidence from literature that supports this hypothesis:
+- Analogous mechanisms in related systems
+- Direct evidence from relevant studies
+- Theoretical frameworks that align with this hypothesis
+- Include citations]
+
+**Key Assumptions:**
+[Explicit statement of assumptions underlying this hypothesis:
+- What must be true for this hypothesis to hold?
+- What conditions or contexts does it require?]
+
+---
+
+### Hypothesis 2: [Concise Title]
+
+**Mechanistic Explanation:**
+[Detailed mechanistic explanation distinct from Hypothesis 1]
+
+**Supporting Evidence:**
+[Evidence supporting this alternative explanation]
+
+**Key Assumptions:**
+[Assumptions underlying this hypothesis]
+
+---
+
+### Hypothesis 3: [Concise Title]
+
+**Mechanistic Explanation:**
+[Detailed mechanistic explanation distinct from previous hypotheses]
+
+**Supporting Evidence:**
+[Evidence supporting this explanation]
+
+**Key Assumptions:**
+[Assumptions underlying this hypothesis]
+
+---
+
+[Continue for Hypothesis 4, 5, etc. if applicable]
+
+---
+
+## 3. Quality Assessment
+
+### Evaluation Against Core Criteria
+
+| Criterion | Hypothesis 1 | Hypothesis 2 | Hypothesis 3 | [H4] | [H5] |
+|-----------|--------------|--------------|--------------|------|------|
+| **Testability** | [Rating & brief note] | [Rating & brief note] | [Rating & brief note] | | |
+| **Falsifiability** | [Rating & brief note] | [Rating & brief note] | [Rating & brief note] | | |
+| **Parsimony** | [Rating & brief note] | [Rating & brief note] | [Rating & brief note] | | |
+| **Explanatory Power** | [Rating & brief note] | [Rating & brief note] | [Rating & brief note] | | |
+| **Scope** | [Rating & brief note] | [Rating & brief note] | [Rating & brief note] | | |
+| **Consistency** | [Rating & brief note] | [Rating & brief note] | [Rating & brief note] | | |
+
+**Rating scale:** Strong / Moderate / Weak
+
+### Detailed Evaluation
+
+#### Hypothesis 1
+**Strengths:**
+- [Specific strength 1]
+- [Specific strength 2]
+
+**Weaknesses:**
+- [Specific weakness 1]
+- [Specific weakness 2]
+
+**Overall Assessment:**
+[Brief summary of hypothesis quality and viability]
+
+#### Hypothesis 2
+[Similar structure]
+
+#### Hypothesis 3
+[Similar structure]
+
+---
+
+## 4. Experimental Designs
+
+### Testing Hypothesis 1: [Title]
+
+**Experiment 1A: [Brief title]**
+
+*Design Type:* [e.g., In vitro dose-response / In vivo knockout / Clinical RCT / Observational cohort / Computational model]
+
+*Objective:* [What specific aspect of the hypothesis does this test?]
+
+*Methods:*
+- **System/Model:** [What system, organism, or population?]
+- **Intervention/Manipulation:** [What is varied or manipulated?]
+- **Measurements:** [What outcomes are measured?]
+- **Controls:** [What control conditions?]
+- **Sample Size:** [Estimated n, with justification if possible]
+- **Analysis:** [Statistical or analytical approach]
+
+*Expected Timeline:* [Rough estimate]
+
+*Feasibility:* [High/Medium/Low, with brief justification]
+
+**Experiment 1B: [Brief title - alternative or complementary approach]**
+[Similar structure to 1A]
+
+---
+
+### Testing Hypothesis 2: [Title]
+
+**Experiment 2A: [Brief title]**
+[Structure as above]
+
+**Experiment 2B: [Brief title]**
+[Structure as above]
+
+---
+
+### Testing Hypothesis 3: [Title]
+
+**Experiment 3A: [Brief title]**
+[Structure as above]
+
+---
+
+## 5. Testable Predictions
+
+### Predictions from Hypothesis 1
+
+1. **Prediction 1.1:** [Specific, measurable prediction]
+   - **Conditions:** [Under what conditions should this be observed?]
+   - **Magnitude:** [Expected effect size or direction, if quantifiable]
+   - **Falsification:** [What observation would falsify this prediction?]
+
+2. **Prediction 1.2:** [Specific, measurable prediction]
+   - **Conditions:** [Conditions]
+   - **Magnitude:** [Expected effect]
+   - **Falsification:** [Falsifying observation]
+
+3. **Prediction 1.3:** [Additional prediction]
+
+---
+
+### Predictions from Hypothesis 2
+
+1. **Prediction 2.1:** [Specific, measurable prediction]
+   - **Conditions:** [Conditions]
+   - **Magnitude:** [Expected effect]
+   - **Falsification:** [Falsifying observation]
+
+2. **Prediction 2.2:** [Additional prediction]
+
+---
+
+### Predictions from Hypothesis 3
+
+1. **Prediction 3.1:** [Specific, measurable prediction]
+   - **Conditions:** [Conditions]
+   - **Magnitude:** [Expected effect]
+   - **Falsification:** [Falsifying observation]
+
+---
+
+## 6. Critical Comparisons
+
+### Distinguishing Between Hypotheses
+
+**Comparison: Hypothesis 1 vs. Hypothesis 2**
+
+*Key Distinguishing Feature:*
+[What is the fundamental difference in mechanism or prediction?]
+
+*Discriminating Experiment:*
+[What experiment or observation would clearly favor one over the other?]
+
+*Outcome Interpretation:*
+- If [Result A], then Hypothesis 1 is supported
+- If [Result B], then Hypothesis 2 is supported
+- If [Result C], then both/neither are supported
+
+---
+
+**Comparison: Hypothesis 1 vs. Hypothesis 3**
+[Similar structure]
+
+---
+
+**Comparison: Hypothesis 2 vs. Hypothesis 3**
+[Similar structure]
+
+---
+
+### Priority Experiments
+
+**Highest Priority Test:**
+[Which experiment would most efficiently distinguish between hypotheses or most definitively test a hypothesis?]
+
+**Justification:**
+[Why is this the highest priority? Consider informativeness, feasibility, and cost]
+
+**Secondary Priority Tests:**
+1. [Second most important experiment]
+2. [Third most important]
+
+---
+
+## 7. Summary & Recommendations
+
+### Summary of Hypotheses
+
+[Brief paragraph summarizing the competing hypotheses and their relationships]
+
+### Recommended Testing Sequence
+
+**Phase 1 (Initial Tests):**
+[Which experiments should be done first? Why?]
+
+**Phase 2 (Contingent on Phase 1 results):**
+[What follow-up experiments depend on initial results?]
+
+**Phase 3 (Validation and Extension):**
+[How to validate findings and extend to broader contexts?]
+
+### Expected Outcomes and Implications
+
+**If Hypothesis 1 is supported:**
+[What would this mean for the field? What new questions arise?]
+
+**If Hypothesis 2 is supported:**
+[Implications and new questions]
+
+**If Hypothesis 3 is supported:**
+[Implications and new questions]
+
+**If multiple hypotheses are partially supported:**
+[How might mechanisms combine or interact?]
+
+### Open Questions
+
+[What questions remain even after these hypotheses are tested?]
+
+---
+
+## References
+
+[List key papers cited in the document, formatted consistently]
+
+1. Author1, A.B., & Author2, C.D. (Year). Title of paper. *Journal Name*, Volume(Issue), pages. DOI or URL
+
+2. [Continue for all citations]
+
+---
+
+## Notes on Using This Template
+
+- Replace all bracketed instructions with actual content
+- Not all sections are mandatory - adapt to your specific hypothesis generation task
+- For simpler phenomena, 3 hypotheses may be sufficient; complex phenomena may warrant 4-5
+- Experimental designs should be detailed enough to be actionable but can be refined later
+- Predictions should be as specific and quantitative as possible
+- The template emphasizes both generating hypotheses and planning how to test them
+- Citation format can be adjusted to field-specific standards

scientific_writer/.claude/skills/hypothesis-generation/references/experimental_design_patterns.md

@@ -0,0 +1,327 @@
+# Experimental Design Patterns
+
+## Common Approaches to Testing Scientific Hypotheses
+
+This reference provides patterns and frameworks for designing experiments across scientific domains. Use these patterns to develop rigorous tests for generated hypotheses.
+
+## Design Selection Framework
+
+Choose experimental approaches based on:
+- **Nature of hypothesis:** Mechanistic, causal, correlational, descriptive
+- **System studied:** In vitro, in vivo, computational, observational
+- **Feasibility:** Time, cost, ethics, technical capabilities
+- **Evidence needed:** Proof-of-concept, causal demonstration, quantitative relationship
+
+## Laboratory Experimental Designs
+
+### In Vitro Experiments
+
+**When to use:** Testing molecular, cellular, or biochemical mechanisms in controlled systems.
+
+**Common patterns:**
+
+#### 1. Dose-Response Studies
+- **Purpose:** Establish quantitative relationship between input and effect
+- **Design:** Test multiple concentrations/doses of intervention
+- **Key elements:**
+  - Negative control (no treatment)
+  - Positive control (known effective treatment)
+  - Multiple dose levels (typically 5-8 points)
+  - Technical replicates (≥3 per condition)
+  - Appropriate statistical analysis (curve fitting, IC50/EC50 determination)
+
+**Example application:**
+"To test if compound X inhibits enzyme Y, measure enzyme activity at 0, 1, 10, 100, 1000 nM compound X concentrations with n=3 replicates per dose."
+
+#### 2. Gain/Loss of Function Studies
+- **Purpose:** Establish causal role of specific component
+- **Design:** Add (overexpression) or remove (knockout/knockdown) component
+- **Key elements:**
+  - Wild-type control
+  - Gain-of-function condition (overexpression, constitutive activation)
+  - Loss-of-function condition (knockout, knockdown, inhibition)
+  - Rescue experiment (restore function to loss-of-function)
+  - Measure downstream effects
+
+**Example application:**
+"Test if protein X causes phenotype Y by: (1) knocking out X and observing phenotype loss, (2) overexpressing X and observing phenotype enhancement, (3) rescuing knockout with X re-expression."
+
+#### 3. Time-Course Studies
+- **Purpose:** Understand temporal dynamics and sequence of events
+- **Design:** Measure outcomes at multiple time points
+- **Key elements:**
+  - Time 0 baseline
+  - Early time points (capture rapid changes)
+  - Intermediate time points
+  - Late time points (steady state)
+  - Sufficient replication at each time point
+
+**Example application:**
+"Measure protein phosphorylation at 0, 5, 15, 30, 60, 120 minutes after stimulus to determine peak activation timing."
+
+### In Vivo Experiments
+
+**When to use:** Testing hypotheses in whole organisms to assess systemic, physiological, or behavioral effects.
+
+**Common patterns:**
+
+#### 4. Between-Subjects Designs
+- **Purpose:** Compare different groups receiving different treatments
+- **Design:** Randomly assign subjects to treatment groups
+- **Key elements:**
+  - Random assignment to groups
+  - Appropriate sample size (power analysis)
+  - Control group (vehicle, sham, or standard treatment)
+  - Blinding (single or double-blind)
+  - Standardized conditions across groups
+
+**Example application:**
+"Randomly assign 20 mice each to vehicle control or drug treatment groups, measure tumor size weekly for 8 weeks, with experimenters blinded to group assignment."
+
+#### 5. Within-Subjects (Repeated Measures) Designs
+- **Purpose:** Each subject serves as own control, reducing inter-subject variability
+- **Design:** Same subjects measured across multiple conditions/time points
+- **Key elements:**
+  - Baseline measurements
+  - Counterbalancing (if order effects possible)
+  - Washout periods (for sequential treatments)
+  - Appropriate repeated-measures statistics
+
+**Example application:**
+"Measure cognitive performance in same participants at baseline, after training intervention, and at 3-month follow-up."
+
+#### 6. Factorial Designs
+- **Purpose:** Test multiple factors and their interactions simultaneously
+- **Design:** Cross all levels of multiple independent variables
+- **Key elements:**
+  - Clear main effects and interactions
+  - Sufficient power for interaction tests
+  - Full factorial or fractional factorial as appropriate
+
+**Example application:**
+"2×2 design crossing genotype (WT vs. mutant) × treatment (vehicle vs. drug) to test whether drug effect depends on genotype."
+
+### Computational/Modeling Experiments
+
+**When to use:** Testing hypotheses about complex systems, making predictions, or when physical experiments are infeasible.
+
+#### 7. In Silico Simulations
+- **Purpose:** Model complex systems, test theoretical predictions
+- **Design:** Implement computational model and vary parameters
+- **Key elements:**
+  - Well-defined model with explicit assumptions
+  - Parameter sensitivity analysis
+  - Validation against known data
+  - Prediction generation for experimental testing
+
+**Example application:**
+"Build agent-based model of disease spread, vary transmission rate and intervention timing, compare predictions to empirical epidemic data."
+
+#### 8. Bioinformatics/Meta-Analysis
+- **Purpose:** Test hypotheses using existing datasets
+- **Design:** Analyze large-scale data or aggregate multiple studies
+- **Key elements:**
+  - Appropriate statistical corrections (multiple testing)
+  - Validation in independent datasets
+  - Control for confounds and batch effects
+  - Clear inclusion/exclusion criteria
+
+**Example application:**
+"Test if gene X expression correlates with survival across 15 cancer datasets (n>5000 patients total), using Cox regression with clinical covariates."
+
+## Observational Study Designs
+
+### When Physical Manipulation is Impossible or Unethical
+
+#### 9. Cross-Sectional Studies
+- **Purpose:** Examine associations at a single time point
+- **Design:** Measure variables of interest in population at one time
+- **Strengths:** Fast, inexpensive, can establish prevalence
+- **Limitations:** Cannot establish temporality or causation
+- **Key elements:**
+  - Representative sampling
+  - Standardized measurements
+  - Control for confounding variables
+  - Appropriate statistical analysis
+
+**Example application:**
+"Survey 1000 adults to test association between diet pattern and biomarker X, controlling for age, sex, BMI, and physical activity."
+
+#### 10. Cohort Studies (Prospective/Longitudinal)
+- **Purpose:** Establish temporal relationships and potentially causal associations
+- **Design:** Follow group over time, measuring exposures and outcomes
+- **Strengths:** Can establish temporality, calculate incidence
+- **Limitations:** Time-consuming, expensive, subject attrition
+- **Key elements:**
+  - Baseline exposure assessment
+  - Follow-up at defined intervals
+  - Minimize loss to follow-up
+  - Account for time-varying confounders
+
+**Example application:**
+"Follow 5000 initially healthy individuals for 10 years, testing if baseline vitamin D levels predict cardiovascular disease incidence."
+
+#### 11. Case-Control Studies
+- **Purpose:** Efficiently study rare outcomes by comparing cases to controls
+- **Design:** Identify cases with outcome, select matched controls, compare exposures
+- **Strengths:** Efficient for rare diseases, relatively quick
+- **Limitations:** Recall bias, selection bias, cannot calculate incidence
+- **Key elements:**
+  - Clear case definition
+  - Appropriate control selection (matching or statistical adjustment)
+  - Retrospective exposure assessment
+  - Control for confounding
+
+**Example application:**
+"Compare 200 patients with rare disease X to 400 matched controls without X, testing if early-life exposure Y differs between groups."
+
+## Clinical Trial Designs
+
+#### 12. Randomized Controlled Trials (RCTs)
+- **Purpose:** Gold standard for testing interventions in humans
+- **Design:** Randomly assign participants to treatment or control
+- **Key elements:**
+  - Randomization (simple, block, or stratified)
+  - Concealment of allocation
+  - Blinding (participants, providers, assessors)
+  - Intention-to-treat analysis
+  - Pre-registered protocol and analysis plan
+
+**Example application:**
+"Double-blind RCT: randomly assign 300 patients to receive drug X or placebo for 12 weeks, measure primary outcome of symptom improvement."
+
+#### 13. Crossover Trials
+- **Purpose:** Each participant receives all treatments in sequence
+- **Design:** Participants crossed over between treatments with washout
+- **Strengths:** Reduces inter-subject variability, requires fewer participants
+- **Limitations:** Order effects, requires reversible conditions, longer duration
+- **Key elements:**
+  - Adequate washout period
+  - Randomized treatment order
+  - Carryover effect assessment
+
+**Example application:**
+"Crossover trial: participants receive treatment A for 4 weeks, 2-week washout, then treatment B for 4 weeks (randomized order)."
+
+## Advanced Design Considerations
+
+### Sample Size and Statistical Power
+
+**Key questions:**
+- What effect size is meaningful to detect?
+- What statistical test will be used?
+- What alpha (significance level) and beta (power) are appropriate?
+- What is expected variability in the measurement?
+
+**General guidelines:**
+- Conduct formal power analysis before experiment
+- For pilot studies, n≥10 per group minimum
+- For definitive studies, aim for ≥80% power
+- Account for potential attrition in longitudinal studies
+
+### Controls
+
+**Types of controls:**
+- **Negative control:** No intervention (baseline)
+- **Positive control:** Known effective intervention (validates system)
+- **Vehicle control:** Delivery method without active ingredient
+- **Sham control:** Mimics intervention without active component (surgery, etc.)
+- **Historical control:** Prior data (weakest, avoid if possible)
+
+### Blinding
+
+**Levels:**
+- **Open-label:** No blinding (acceptable for objective measures)
+- **Single-blind:** Participants blinded (reduces placebo effects)
+- **Double-blind:** Participants and experimenters blinded (reduces bias in assessment)
+- **Triple-blind:** Participants, experimenters, and analysts blinded (strongest)
+
+### Replication
+
+**Technical replicates:** Repeated measurements on same sample
+- Reduce measurement error
+- Typically 2-3 replicates sufficient
+
+**Biological replicates:** Independent samples/subjects
+- Address biological variability
+- Critical for generalization
+- Minimum: n≥3, preferably n≥5-10 per group
+
+**Experimental replicates:** Repeat entire experiment
+- Validate findings across time, equipment, operators
+- Gold standard for confirming results
+
+### Confound Control
+
+**Strategies:**
+- **Randomization:** Distribute confounds evenly across groups
+- **Matching:** Pair similar subjects across conditions
+- **Blocking:** Group by confound, then randomize within blocks
+- **Statistical adjustment:** Measure confounds and adjust in analysis
+- **Standardization:** Keep conditions constant across groups
+
+## Selecting Appropriate Design
+
+**Decision tree:**
+
+1. **Can variables be manipulated?**
+   - Yes → Experimental design (RCT, lab experiment)
+   - No → Observational design (cohort, case-control, cross-sectional)
+
+2. **What is the system?**
+   - Cells/molecules → In vitro experiments
+   - Whole organisms → In vivo experiments
+   - Humans → Clinical trials or observational studies
+   - Complex systems → Computational modeling
+
+3. **What is the primary goal?**
+   - Mechanism → Gain/loss of function, dose-response
+   - Causation → RCT, cohort study with good controls
+   - Association → Cross-sectional, case-control
+   - Prediction → Modeling, machine learning
+   - Temporal dynamics → Time-course, longitudinal
+
+4. **What are the constraints?**
+   - Time limited → Cross-sectional, in vitro
+   - Budget limited → Computational, observational
+   - Ethical concerns → Observational, in vitro
+   - Rare outcome → Case-control, meta-analysis
+
+## Integrating Multiple Approaches
+
+Strong hypothesis testing often combines multiple designs:
+
+**Example: Testing if microbiome affects cognitive function**
+1. **Observational:** Cohort study showing association between microbiome composition and cognition
+2. **Animal model:** Germ-free mice receiving microbiome transplants show cognitive changes
+3. **Mechanism:** In vitro studies showing microbial metabolites affect neuronal function
+4. **Clinical trial:** RCT of probiotic intervention improving cognitive scores
+5. **Computational:** Model predicting which microbiome profiles should affect cognition
+
+**Triangulation approach:**
+- Each design addresses different aspects/limitations
+- Convergent evidence from multiple approaches strengthens causal claims
+- Start with observational/in vitro, then move to definitive causal tests
+
+## Common Pitfalls
+
+- Insufficient sample size (underpowered)
+- Lack of appropriate controls
+- Confounding variables not accounted for
+- Inappropriate statistical tests
+- P-hacking or multiple testing without correction
+- Lack of blinding when subjective assessments involved
+- Failure to replicate findings
+- Not pre-registering analysis plans (clinical trials)
+
+## Practical Application for Hypothesis Testing
+
+When designing experiments to test hypotheses:
+
+1. **Match design to hypothesis specifics:** Causal claims require experimental manipulation; associations can use observational designs
+2. **Start simple, then elaborate:** Pilot with simple design, then add complexity
+3. **Plan controls carefully:** Controls validate the system and isolate the specific effect
+4. **Consider feasibility:** Balance ideal design with practical constraints
+5. **Plan for multiple experiments:** Rarely does one experiment definitively test a hypothesis
+6. **Pre-specify analysis:** Decide statistical tests before data collection
+7. **Build in validation:** Independent replication, orthogonal methods, convergent evidence