Skip to main content
`Ctrl`+`K`

# Cosmology I/O & Convert

## Introduction

The `astropy.cosmology.io` package provides a unified interface for reading, writing, and converting |Cosmology| objects. Most of the features of this package are accessible through the |Cosmology| class, which provides the methods |Cosmology.read|, |Cosmology.write|, |Cosmology.to_format|, and |Cosmology.from_format| for reading, writing, and converting |Cosmology| objects, respectively.

## Getting Started: Reading and Writing

The |Cosmology| class includes two methods, |Cosmology.read| and |Cosmology.write|, that make it possible to read from and write to files.

The registered `read` / `write` formats include “ascii.ecsv” and “ascii.html”, like for Table. Also, custom `read` / `write` formats may be registered into the Astropy Cosmology I/O framework. For more information on the built-in formats, see Built-in Cosmology To/From Formats, or Custom Cosmology I/O formats for information on registering custom formats.

Writing a cosmology instance requires only the file location and optionally, or if the file format cannot be inferred, a keyword argument “format”. Additional positional arguments and keyword arguments are passed to the relevant writer methods.

    >>> from astropy.cosmology import Planck18
    >>> Planck18.write("example_cosmology.ecsv", format="ascii.ecsv")

Reading back the cosmology is done from |Cosmology|.

    >>> from astropy.cosmology import Cosmology
    >>> cosmo = Cosmology.read("example_cosmology.ecsv", format="ascii.ecsv")
    >>> cosmo == Planck18
    True

More specific cosmology classes can be used, providing default values for missing information (see Cosmology I/O Details). However using the base class is safest as it provides no default information and therefore requires the file to have all necessary information to describe a cosmology.

To see a list of the available read/write file formats:

    >>> from astropy.cosmology import Cosmology
    >>> Cosmology.read.list_formats()
      Format   Read Write Auto-identify
    ---------- ---- ----- -------------
    ascii.ecsv  Yes   Yes           Yes
    ascii.html  Yes   Yes           Yes
    ascii.mrt   Yes   Yes           Yes

    >>> Cosmology.write.list_formats()
       Format   Read Write Auto-identify
    ----------- ---- ----- -------------
     ascii.ecsv  Yes   Yes           Yes
     ascii.html  Yes   Yes           Yes
    ascii.latex   No   Yes           Yes
      ascii.mrt  Yes   Yes           Yes

This list will include both built-in and registered 3rd-party formats.

## Getting Started: Converting Formats

Reading and writing |Cosmology| objects go through intermediate representations, often a dict or |QTable| instance. These intermediate representations are accessible through the methods |Cosmology.to_format| / |Cosmology.from_format|.

|Cosmology.to_format| / |Cosmology.from_format| parse a Cosmology to/from another python object. This can be useful for e.g., iterating through an MCMC of cosmological parameters or printing out a cosmological model to a journal format, like latex or HTML. When 3rd party cosmology packages register with Astropy’s Cosmology I/O, `to/from_format` can be used to convert cosmology instances between packages!

Another pre-registered format is “table”, for converting a |Cosmology| to and from a |QTable|.

    >>> from astropy.cosmology import Planck18
    >>> ct = Planck18.to_format("astropy.table")
    >>> ct
    <QTable length=1>
      name        H0        Om0    Tcmb0    Neff      m_nu      Ob0
             km / (Mpc s)            K                 eV
      str8     float64    float64 float64 float64  float64[3] float64
    -------- ------------ ------- ------- ------- ----------- -------
    Planck18        67.66 0.30966  2.7255   3.046 0.0 .. 0.06 0.04897

Now this |QTable| can be used to load a new cosmological instance identical to the |Planck18| cosmology from which it was created.

    >>> cosmo = Cosmology.from_format(ct, format="astropy.table")
    >>> print(cosmo)
    FlatLambdaCDM(name="Planck18", H0=67.66 km / (Mpc s), Om0=0.30966,
                  Tcmb0=2.7255 K, Neff=3.046, m_nu=[0. 0. 0.06] eV, Ob0=0.04897)

Perhaps most usefully, |QTable| itself has `read/write` methods with numerous options, e.g. FITS, that now work with |Cosmology|.

To see the a list of the available conversion formats:

    >>> from astropy.cosmology import Cosmology
    >>> Cosmology.to_format.list_formats()
          Format      Read Write Auto-identify
    ----------------- ---- ----- -------------
    astropy.cosmology  Yes   Yes           Yes
        astropy.model  Yes   Yes           Yes
          astropy.row  Yes   Yes           Yes
        astropy.table  Yes   Yes           Yes
              mapping  Yes   Yes           Yes
                 yaml  Yes   Yes            No

This list will include both built-in and registered 3rd-party formats.

## Using Cosmology I/O

More details are provided in the following pages:

- Cosmology I/O Details
  - Cosmology in a Pickle
  - Renaming Fields
  - I/O from Subclasses
- Built-in Cosmology To/From Formats
  - Cosmology
  - Mapping
  - Table
  - Model
  - YAML
  - Row
- Built-in Cosmology Read/Write Formats
  - ECSV
  - LaTeX
  - HTML
  - MRT
- Custom Cosmology I/O formats
  - Custom Cosmology To/From Formats
  - Custom Cosmology Readers/Writers

## Reference/API

### astropy.cosmology.io Module

I/O subpackage for cosmology.

This subpackage contains classes and functions for reading, writing and converting cosmology objects to and from various formats.

User access to the I/O functionality is provided through the methods on the `Cosmology` class (and its subclasses) and its instances:

- |Cosmology.read| for reading from a file,

- |Cosmology.write| for writing to a file,

- |Cosmology.from_format| to construct a Cosmology from an object

- |Cosmology.to_format| to convert a Cosmology to an object

#### Classes

`CosmologyFromFormat`(instance, cosmo_cls) | Transform object to a `Cosmology`.
`CosmologyRead`(instance, cosmo_cls) | Read and parse data to a `Cosmology`.
`CosmologyToFormat`(instance, cls) | Transform this Cosmology to another format.
`CosmologyWrite`(instance, cls) | Write this Cosmology object out in the specified format.

#### Class Inheritance Diagram