Two-Point Workflow Guide

Version ?env:FIRECROWN_VERSION

def doc_theme():
    return theme_minimal() + theme(
        panel_grid_minor=element_line(color="gray", linetype="--"),
    )

This guide shows you how to work with two-point statistics in Firecrown, from obtaining data to computing predictions. Use this as a roadmap to navigate the detailed tutorials based on your specific needs.

Quick Start

Choose your starting point:

I Have a SACC File

If you’re working with existing data or simulations in SACC format:

1. Loading SACC Data — Extract metadata and measurements
2. Factory Basics — Construct TwoPoint objects with modeling choices
3. Scale Cuts (optional) — Restrict to valid physical ranges
4. Integration Methods (optional) — Tune computation accuracy/speed

I’m Generating Data from Scratch

If you’re creating forecasts or simulated analyses:

1. Two-Point Generators — Create metadata and data programmatically
2. Factory Basics — Construct TwoPoint objects with modeling choices
3. Scale Cuts (optional) — Restrict to valid physical ranges
4. Integration Methods (optional) — Tune computation accuracy/speed

I’m New to Firecrown

Start with Two-Point Framework for conceptual foundations, then follow one of the workflows above.

Complete Workflow

All two-point analyses in Firecrown follow this general pattern:

graph TD
  A["Start: Choose Data Source"]
  A --> B1["Generate from Scratch<br/>(Two-Point Generators)"]
  A --> B2["Extract from SACC<br/>(Loading SACC Data)"]
  B1 --> B1F["Optional: Filter with<br/>Bin Pair Selectors"]
  B2 --> B2F["Optional: Filter with<br/>Bin Pair Selectors"]
  B1F --> C["Metadata + Optional Data"]
  B2F --> C
  C --> D["Apply Scale Cuts<br/>(Optional)"]
  D --> E["TwoPointFactory<br/>(Factory Basics)"]
  E --> F["TwoPoint Objects"]
  F --> G["Compute Theory<br/>(Integration Methods)"]
  G --> H["Theory Vector / Likelihood"]

Figure 1: Complete two-point analysis workflow

Detailed Steps

Step 1: Obtain Metadata and Data

Choose one approach based on your data source:

From Generators (Tutorial)

Create metadata and data programmatically for forecasts or simulations:

• Generate LSST-SRD compliant redshift distributions
• Define measurement types (galaxy counts, weak lensing, etc.)
• Configure systematics models upfront
• Optional: Apply BinPairSelector to include only specific bin pair combinations
• Output: Metadata layouts (TwoPointHarmonic/TwoPointReal) with optional data

When to use: Creating forecasts, Fisher forecasts, synthetic analyses, or testing new models.

From SACC Files (Tutorial)

Extract both metadata and measurements from standardized SACC files:

• Full extraction (recommended) gets metadata + data together
• Legacy approach extracts metadata only, loads data separately
• Optional: Apply BinPairSelector to extract only specific bin pair combinations
• Validates consistency of extracted components
• Output: Metadata layouts with optional measurements (TwoPointMeasurement)

When to use: Analyzing real observations, working with pre-existing simulations, or integrating with other analysis pipelines.

Filtering with Bin Pair Selectors (Tutorial)

Both workflows support optional filtering to control which bin pair combinations are included:

• Auto-correlations only: Same bin correlated with itself
• Cross-correlations only: Different bins correlated together
• Measurement-specific: Only source (shear) or lens (counts) measurements
• Custom combinations: Use logical operators (AND, OR, NOT) to build complex criteria

See Bin Pair Selectors for detailed examples and available selector types.

Step 2: Construct TwoPoint Objects (Tutorial)

The TwoPointFactory builds TwoPoint objects by:

1. Inspecting measurement types in your metadata
2. Delegating to appropriate source factories:
   • Galaxies.COUNTS → NumberCountsFactory
   • Galaxies.SHEAR_E / Galaxies.SHEAR_T / … → WeakLensingFactory
3. Applying modeling choices (systematics, tracers, scales)

Each TwoPoint object can be constructed from:

• Layout only (metadata) → Theory predictions for forecasts
• Measurement (metadata + data) → Theory + data for likelihood evaluation

Key feature: Multiple instances of the same source factory can be tied to different TypeSource values, enabling distinct modeling choices for subpopulations (e.g., red vs. blue galaxies).

Step 3: Apply Scale Cuts (Optional) (Tutorial)

Restrict analysis to physically valid ranges where your models are accurate:

• Define valid scale ranges per tracer combination
• Use TwoPointBinFilterCollection for flexible filtering # Tutorial Reference {#sec-tutorial-reference}

Tutorial	Purpose	Use When
Framework	Conceptual foundations	Learning Firecrown concepts
Bin Selectors	Filter bin pair combinations	Selecting specific correlations
Generators	Create data from scratch	Forecasts, simulations, testing
Loading SACC	Extract from SACC files	Real data, existing simulations
Factory Basics	Construct TwoPoint objects	All analyses (required)
Scale Cuts	Filter by physical scales	Limited model validity
Integration	Tune computation methods	Accuracy/speed optimization

When to tune: High-precision requirements, large-scale analyses, or computational optimization.

Tutorial Reference

Tutorial	Purpose	Use When
Framework	Conceptual foundations	Learning Firecrown concepts
Generators	Create data from scratch	Forecasts, simulations, testing
Loading SACC	Extract from SACC files	Real data, existing simulations
Factory Basics	Construct TwoPoint objects	All analyses (required)
Scale Cuts	Filter by physical scales	Limited model validity
Integration	Tune computation methods	Accuracy/speed optimization