# redshift¶

speclite.redshift.redshift(z_in, z_out, data_in=None, data_out=None, rules=[])[source] [edit on github]

Transform spectral data from redshift z_in to z_out.

Each quantity X is transformed according to a power law:

```X_out = X_in * ((1 + z_out) / (1 + z_in))**exponent
```

where exponents are specified with the `rules` argument. Exponents for some common cases are listed in the table below.

Exponent

Quantities

0

flux density in photons/(s*cm^2*Ang)

+1

wavelength, wavelength error, flux density in ergs/(s*cm^2*Hz)

-1

frequency, frequency error, flux density in ergs/(s*cm^2*Ang)

+2

inverse variance of flux density in ergs/(s*cm^2*Ang)

-2

inverse variance of flux density in ergs/(s*cm^2*Hz)

For example, to transform separate wavelength and flux arrays using the SDSS standard units of Ang and 1e-17 erg/(s*cm^2*Ang):

```>>> wlen = np.arange(4000., 10000.)
>>> flux = np.ones(wlen.shape)
>>> result = redshift(z_in=0, z_out=1, rules=[
... dict(name='wlen', exponent=+1, array_in=wlen),
... dict(name='flux', exponent=-1, array_in=flux)])
>>> result.dtype
dtype([('wlen', '<f8'), ('flux', '<f8')])
>>> result['flux']
0.5
```

The same calculation could be performed with the input data stored in a numpy structured array, in which case any additional fields are copied to the output array:

```>>> data = np.empty(6000, dtype=[
... ('wlen', float), ('flux', float), ('maskbits', int)])
>>> data['wlen'] = np.arange(4000., 10000.)
>>> data['flux'] = np.ones_like(data['wlen'])
>>> result = redshift(z_in=0, z_out=1, data_in=data, rules=[
... dict(name='wlen', exponent=+1),
... dict(name='flux', exponent=-1)])
>>> result.dtype
dtype([('wlen', '<f8'), ('flux', '<f8'), ('maskbits', '<i8')])
>>> result['flux']
0.5
```

The transformed result is always a numpy structured array, with field (column) names determined by the rules you provide.

The usual numpy broadcasting rules apply in the transformation expression above so, for example, the same redshift can be applied to multiple spectra, or different redshifts can be applied to the same spectrum with appropriate input shapes.

Input arrays can have associated masks and these will be propagated to the output. Input arrays can also have units but these will not be used or propagated to the output since numpy structured arrays do not support per-column units.

Parameters:
z_infloat or numpy.ndarray

Redshift(s) of the input spectral data, which must all be > -1.

z_outfloat or numpy.ndarray

Redshift(s) of the output spectral data, which must all be > -1.

data_innumpy.ndarray

Structured numpy array containing input spectrum data to transform. If none is specified, then all quantities must be provided as numpy arrays in the rules.

data_outnumpy.ndarray

Structured numpy array where output spectrum data should be written. If none is specified, then an appropriately sized array will be allocated and returned. Use this method to take control of the memory allocation and, for example, re-use the same output array for a sequence of transforms.

rulesiterable

An iterable object whose elements are dictionaries. Each dictionary specifies how one quantity will be transformed and must contain ‘name’ and ‘exponent’ values. If an ‘array_in’ value is also specified, it should refer to a numpy array containing the input values to transform. Otherwise, `data_in[<name>]` is assumed to contain the input values to transform. If no `rules` are specified and `data_in` is provided, then `data_out` is just a copy of `data_in`.

Returns:
numpy.ndarray

Array of spectrum data with the redshift transform applied. Equal to data_out when set, otherwise a new array is allocated. If `data_in` is specified, then any fields not listed in `rules` are copied to `data_out`, so effectively have an implicit exponent of zero.