photoz_distortion
================================================

Apply photometric redshift systematic biases to n(z) distributions

+-------------+-------------------------------------------------------+
| File        | number_density/photoz_distortion/photoz_distortion.py |
+-------------+-------------------------------------------------------+
| Attribution | CosmoSIS Team                                         |
+-------------+-------------------------------------------------------+
| URL         |                                                       |
+-------------+-------------------------------------------------------+

This module applies systematic biases to photometric redshift n(z) distributions
to model the effects of photo-z estimation errors. It can apply three types of
distortions:

1. Additive bias: Shift in mean redshift (delta_z offset)
2. Broadening: Increase in redshift scatter around the mean
3. Skewness: Asymmetric redistribution toward higher redshifts

The module can also add a population of catastrophic outliers using either
a Gaussian 'island' or uniform distribution model. Biases can be applied
globally or per-bin.


Assumptions
-----------

 - Photo-z systematics can be modeled as shifts, broadening, and skewness
 - Input n(z) distributions are well-sampled



Setup Parameters
----------------

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Default
     - Description

   * - mean
     - bool
     - 
     - Whether to apply additive bias (mean shift)
   * - width
     - bool
     - 
     - Whether to apply broadening (width increase)
   * - tail
     - bool
     - 
     - Whether to apply skewness (tail asymmetry)
   * - bias_per_bin
     - bool
     - 
     - Whether biases are specified per bin or globally
   * - sample
     - str
     - 
     - Name of the section containing n(z) to be modified
   * - catastrophic_outliers
     - str
     - 
     - Model for catastrophic outliers ('island' or 'uniform')


Input values
----------------

.. list-table::
   :header-rows: 1

   * - Section
     - Name
     - Type
     - Default
     - Description

   * - sample_section
     - nzbin
     - int
     - 
     - Number of redshift bins
   * - 
     - z
     - real 1d
     - 
     - Redshift sample values
   * - 
     - bin_{i}
     - real 1d
     - 
     - n(z) values for bin i to be modified
   * - 
     - bias_{i}
     - real
     - 
     - Additive bias for bin i (if mean=true and bias_per_bin=true)
   * - 
     - bias_1
     - real
     - 
     - Global additive bias (if mean=true and bias_per_bin=false)
   * - 
     - S_z_{i}
     - real
     - 
     - Broadening parameter for bin i (if width=true and bias_per_bin=true)
   * - 
     - S_z_1
     - real
     - 
     - Global broadening parameter (if width=true and bias_per_bin=false)
   * - 
     - T_z_{i}
     - real
     - 
     - Skewness parameter for bin i (if tail=true and bias_per_bin=true)
   * - 
     - T_z_1
     - real
     - 
     - Global skewness parameter (if tail=true and bias_per_bin=false)
   * - 
     - method
     - str
     - 
     - Catastrophic outlier method ('island' or 'uniform')
   * - 
     - fcat
     - real
     - 
     - Fraction of catastrophic outliers
   * - 
     - dzcat
     - real
     - 
     - Redshift range for catastrophic outliers
   * - 
     - zcat0
     - real
     - 
     - Central redshift for catastrophic outlier region
   * - 
     - zcat
     - real
     - 
     - Central redshift for catastrophic outlier distribution
   * - 
     - sigcat
     - real
     - 
     - Width of catastrophic outlier Gaussian (if method='island')


Output values
----------------


.. list-table:: Output values
   :header-rows: 1

   * - Section
     - Name
     - Type
     - Description

   * - sample_section
     - z
     - real 1d
     - Extended redshift grid including padding
   * - 
     - bin_{i}
     - real 1d
     - Modified n(z) values for bin i with applied systematics