Read files¶

File contents¶

The Mojito L1 files contain the following quantities:

Metadata regarding the L01 pipeline that produced it, such as the pipeline name and version (see MojitoL1File)
Time-delay interferometry (TDI) observables, namely single-link \(\eta\), Michelson XYZ and quasi-orthogonal AET variables (see TDI)
Estimates of the light travel times (LTTs) and their derivatives, used to build the response function (see LTT)
Estimates of the spacecraft orbits, including the spacecraft positions and velocities in the BCRS, used to build the response function (see Orbits)
Estimates of the overall instrumental noise in single-link \(\eta\), Michelson XYZ and quasi-orthogonal AET variables as complex time and frequency-dependent covariance matrices, see NoiseEstimates

Note that not all Mojito L1 files contain all the above quantities. Typically,

A signal brick only contains the TDI, LTT, orbits quantities,
A noise brick contains all of the above quantities.

Files obtained by combining multiple bricks contain the quantities from all the original bricks.

Reading a single file¶

Use MojitoL1File to read data from a Mojito L1 file.

Then, access the different quantities using the corresponding attributes.

from mojito import MojitoL1File

with MojitoL1File("path/to/file.h5") as f:

    # TDI observables
    x2 = f.tdis.x2[:]  # TDI X2 observable in Hz
    y2 = f.tdis.y2[:]  # TDI Y2 observable in Hz
    z2 = f.tdis.z2[:]  # TDI Z2 observable in Hz

    # Complete set of TDI observables in Doppler units
    xyz = f.tdis.xyz_doppler  # TDI XYZ in Doppler units
    aet = f.tdis.aet_doppler  # TDI AET in Doppler units

Reading incomplete files¶

Note that the reader does not perform any validation of the file contents. As a consequence, it can be used to read incomplete Mojito L1 files, e.g., files that only contain TDI observables without orbits or noise estimates.

To check whether a given quantity is present in the file, use the corresponding is_complete attribute. For example, to check whether the file contains the complete set of TDI observables, use f.tdis.is_complete.

You can check the presence of all quantities using the MojitoL1File.is_complete attribute, which is True if and only if all groups and quantities are present in the file.

Reading multiple files¶

The reader can also be used to read multiple Mojito L1 files at once, by passing a list of file paths to MojitoL1File. In this case, the reader will look for the requested quantity in all files, and combine them appropriately if they are present in multiple files. This is useful to read files obtained by combining multiple bricks.

The relevant combination operations are performed. For example, TDI observables are summed across files, while quality flags are combined with a logical OR operation.

from mojito import MojitoL1File

with MojitoL1File(["file1.h5", "file2.h5"]) as f:

    # First 1000 samples of TDI X2 observable in Hz, summed across files
    x2 = f.tdis.x2[:1000]

    # First 1000 samples of TDI XYZ observables in Doppler units, summed
    # across files and lazily normalized by the laser frequency
    xyz = f.tdis.xyz_doppler[:1000]

    # First 1000 samples of quality flags for TDI XYZ observables
    xyz_flags = f.tdis.xyz_flags[:1000]

    # First 1000 samples of TDI time grid (must be consistent across files)
    time = f.tdis.time_sampling.time[:1000]

All operations are performed lazily, i.e., only the requested slice of data is read from disk and combined when the corresponding attribute is accessed. See mojito.lazy for more details on the lazy dataset classes used for this.

Warning

Note that some consistency checks are available, but they are performed when accessing specific properties or by calling MojitoL1File.check_consistent(), not at file open time.

Reference¶

class mojito.reader.MojitoL1File(paths, mode='r')[source]¶

Provides access to Mojito L1 files.

Can open a single Mojito L1 file or combine multiple files lazily, aggregating datasets via the correct mathematical operations.

>>> with MojitoL1File(["file1.h5", "file2.h5"]) as f:
...     etas = f.tdis.eta_doppler[:]
...     times = f.tdis.time_sampling.t()

Multiple files can only be accessed in read-only mode, as data is aggregated. However, single files can be opened in write mode (using the mode parameter) to create or modify Mojito L1 files. Check writer for more details on how to create Mojito L1 files.

Warning

No consistency checks are performed across files, so users must ensure that combined files are compatible (e.g., time samplings must be identical, orbits and LTTs must be consistent, laser frequencies must be identical, etc.).

All quantities are accessed lazily. As a consequence, it is possible to read incomplete files (e.g., files missing some groups, attributes or datasets). Errors will only be raised when trying to access missing quantities.

Use the is_complete property of each data class (e.g., TDI.is_complete) to check if all expected datasets are present in each group. The global MojitoL1File.is_complete property checks if all expected datasets are present in all expected groups.

Note that most attributes are cached for efficiency. They will become invalid after closing the file, so you must not access them then.

Parameters:

paths (str | Path | list[str | Path]) – Path or list of paths to Mojito L1 files. If a list is provided, files are combined lazily.
mode (Literal['r', 'r+', 'a', 'w', 'w-'], default: 'r') – File open mode (default “r” for read-only). Must be “r” for multi-file input, as multi-file aggregation is only supported in read-only mode.

files¶: The underlying HDF5 file objects.

Raises:: ValueError – If no paths are provided or if multi-file input is used with a mode other than “r”.

check_consistent()[source]¶

Check that all files are consistent.

We check that all groups are consistent, and that laser frequencies and versions are identical across files.

Return type:: None

close()[source]¶

Close all open files.

Return type:: None

property is_combined: bool¶: Check if this MojitoL1File combines multiple files.

property is_complete: bool¶: Check that the HDF5 file is a complete L1 file.

property laser_frequencies: list[float][source]¶: Laser frequencies used in the simulations [Hz].

property laser_frequency: float[source]¶: Laser frequency used in the simulation [Hz].

property lolipops_version: str[source]¶: Version of lolipops used to generate the files.

property lolipops_versions: list[str][source]¶: Versions of lolipops used to generate the files.

property ltts: LTT[source]¶

Light travel time estimates (and derivatives).

We provide improved estimates of the six one-way light travel times between the three spacecraft, including relativistic corrections, as well as their time derivatives.

property noise_estimates: NoiseEstimates[source]¶

Estimated noise covariance matrices.

We provide estimates for TDI XYZ, TDI AET, and single-link \(eta\).

Assuming local stationarity, the noise covariance matrix depends on time and frequency only. Noise estimates are stored as diagonal covariance matrices. We provide both strain noise (i.e., noise at the test masses) and readout noise (i.e., electronics noise added to test mass measurements).

property orbits: Orbits[source]¶

Spacecraft orbits.

We provide the positions and velocities of the three spacecraft in the Barycentric Celestial Reference System (BCRS).

property pipeline_names: list[str][source]¶: Name of the pipeline for each file.

property tdis: TDI[source]¶

Time-delay interferometry observables and quality flags.

We provide the second-generation Michelson combinations XYZ, the quasi-orthogonal second-generation channels AET, and the six single-link \(\eta\) observables.

We also provide quality flags for the \(\eta\), XYZ, and AET observables.

class mojito.reader.TDI(groups, laser_frequency)[source]¶

Provides access to TDI observables stored in Mojito L1 files.

No consistency checks are performed across groups. Use the check_consistent() method to check for consistency.

Parameters:

groups (list[Group]) – List of HDF5 groups containing TDI observables datasets.
laser_frequency (float) – Approximate laser frequency used in the simulation [Hz].

groups¶: List of HDF5 groups containing TDI observables datasets.

DATASETS¶: List of dataset names expected in each group.

GROUPS¶: List of group names expected in each group.

Raises:: ValueError – If there are no groups.

property a2: DatasetLike[source]¶

TDI A2 observable [Hz].

Returns:: TDI A2 observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property aet_doppler: DatasetLike[source]¶

TDI AET observables in Doppler units [dimensionless].

AET are obtained by stacking and normalizing A2, E2, T2 by the approximate laser frequency. This is a good approximation of the Doppler observables.

Returns:: TDI AET observables in Doppler units.
Return type:: DatasetLike of shape (time_sampling.size, 3)

property aet_flags: DatasetLike[source]¶

Quality flags applicable for all AET observables.

Flags are either 0 (data can be safely used) or 1 (data should not be used, i.e. gap).

Note

In the current implementation, the same quality flags are used for both XYZ and AET observables, see the xyz_flags attribute.

Returns:: Flags for AET observables.
Return type:: DatasetLike of shape (time_sampling.size,)

check_consistent()[source]¶

Check if time samplings are equal across groups.

Raises:: ValueError – If time samplings are inconsistent across groups.
Return type:: None

property e2: DatasetLike[source]¶

TDI E2 observable [Hz].

Returns:: TDI E2 observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property eta_12: DatasetLike[source]¶

TDI \(\eta_{12}\) observable [Hz].

Returns:: TDI \(\eta_{12}\) observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property eta_13: DatasetLike[source]¶

TDI \(\eta_{13}\) observable [Hz].

Returns:: TDI \(\eta_{13}\) observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property eta_21: DatasetLike[source]¶

TDI \(\eta_{21}\) observable [Hz].

Returns:: TDI \(\eta_{21}\) observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property eta_23: DatasetLike[source]¶

TDI \(\eta_{23}\) observable [Hz].

Returns:: TDI \(\eta_{23}\) observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property eta_31: DatasetLike[source]¶

TDI \(\eta_{31}\) observable [Hz].

Returns:: TDI \(\eta_{31}\) observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property eta_32: DatasetLike[source]¶

TDI \(\eta_{32}\) observable [Hz].

Returns:: TDI \(\eta_{32}\) observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property eta_doppler: DatasetLike[source]¶

TDI \(\eta\) observables in Doppler units [dimensionless].

The single-link \(\eta\) observables are ordered according to lisaconstants.indexing.MOSAS.

Returns:: TDI \(\eta\) observables in Doppler units.
Return type:: DatasetLike of shape (time_sampling.size, 6)

property eta_flags: DatasetLike[source]¶

Quality flags applicable for all \(\eta\) observables.

Flags are either 0 (data can be safely used) or 1 (data should not be used, i.e. gap).

Returns:: Flags for \(\eta\) observables.
Return type:: DatasetLike of shape (time_sampling.size,)

property is_complete: bool¶: Check if all groups and datasets are present in each group.

property t2: DatasetLike[source]¶

TDI T2 observable [Hz].

Returns:: TDI T2 observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property time_sampling: UniformTimeSampling[source]¶: Uniform time sampling of TDI observables.

property x2: DatasetLike[source]¶

TDI X2 observable [Hz].

Returns:: TDI X2 observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property xyz_doppler: DatasetLike[source]¶

TDI XYZ observables in Doppler units [dimensionless].

XYZ are obtained by stacking and normalizing X2, Y2, Z2 by the approximate laser frequency. This is a good approximation of the Doppler observables.

Returns:: TDI XYZ observables in Doppler units.
Return type:: DatasetLike of shape (time_sampling.size, 3)

property xyz_flags: DatasetLike[source]¶

Quality flags applicable for all XYZ observables.

Flags are either 0 (data can be safely used) or 1 (data should not be used, i.e. gap).

Returns:: Flags for XYZ observables.
Return type:: DatasetLike of shape (time_sampling.size,)

property y2: DatasetLike[source]¶

TDI Y2 observable [Hz].

Returns:: TDI Y2 observable.
Return type:: DatasetLike of shape (time_sampling.size,)

property z2: DatasetLike[source]¶

TDI Z2 observable [Hz].

Returns:: TDI Z2 observable.
Return type:: DatasetLike of shape (time_sampling.size,)

class mojito.reader.LTT(groups)[source]¶

Provides access to light travel times stored in Mojito L1 files.

No consistency checks are performed across groups. In particular, we do not check that LTT estimates are identical across groups (we only return one). Use the check_consistent() method to check for consistency.

Parameters:: groups (list[Group]) – List of HDF5 groups containing the LTT observables datasets.

groups¶: List of HDF5 groups containing the LTT observables datasets.

DATASETS¶: List of dataset names expected in each group.

GROUPS¶: List of group names expected in each group.

Raises:: ValueError – If there are no groups.

check_consistent(*, quick=False, chunk=100000)[source]¶

Check if time samplings and LTT estimates are equal across groups.

This can be an expensive operation, since LTT estimates need to be read from disk. If you only want to check that time samplings are consistent across groups, set quick=True to only check time samplings.

To limit memory usage when checking LTT estimates, you can set the chunk size to read and compare the LTT estimates in smaller chunks.

Parameters:

quick (bool, default: False) – Whether to only check time samplings for consistency, without checking that LTT estimates are identical across groups. This is a much faster check, since it does not require reading LTT estimates from disk, but it is less strict.
chunk (int, default: 100000) – Chunk size to use when checking LTT estimates for consistency. This limits memory usage when checking large datasets.

Raises:

ValueError – If time samplings are inconsistent across groups, or if LTT estimates are inconsistent across groups when quick=False.

Return type:

None

property is_complete: bool¶: Check if all groups and datasets are present in each group.

property ltt_12: DatasetLike[source]¶

Improved estimate of LTT 12 [s].

Returns:: Improved estimate of LTT 12.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_13: DatasetLike[source]¶

Improved estimate of LTT 13 [s].

Returns:: Improved estimate of LTT 13.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_21: DatasetLike[source]¶

Improved estimate of LTT 21 [s].

Returns:: Improved estimate of LTT 21.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_23: DatasetLike[source]¶

Improved estimate of LTT 23 [s].

Returns:: Improved estimate of LTT 23.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_31: DatasetLike[source]¶

Improved estimate of LTT 31 [s].

Returns:: Improved estimate of LTT 31.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_32: DatasetLike[source]¶

Improved estimate of LTT 32 [s].

Returns:: Improved estimate of LTT 32.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_derivative_12: DatasetLike[source]¶

Improved estimate of LTT derivative 12 [s/s].

Returns:: Improved estimate of LTT derivative 12.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_derivative_13: DatasetLike[source]¶

Improved estimate of LTT derivative 13 [s/s].

Returns:: Improved estimate of LTT derivative 13.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_derivative_21: DatasetLike[source]¶

Improved estimate of LTT derivative 21 [s/s].

Returns:: Improved estimate of LTT derivative 21.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_derivative_23: DatasetLike[source]¶

Improved estimate of LTT derivative 23 [s/s].

Returns:: Improved estimate of LTT derivative 23.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_derivative_31: DatasetLike[source]¶

Improved estimate of LTT derivative 31 [s/s].

Returns:: Improved estimate of LTT derivative 31.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_derivative_32: DatasetLike[source]¶

Improved estimate of LTT derivative 32 [s/s].

Returns:: Improved estimate of LTT derivative 32.
Return type:: DatasetLike of shape (time_sampling.size,)

property ltt_derivatives: DatasetLike[source]¶

Improved estimates of all LTT derivatives [s/s].

Links are ordered according to lisaconstants.indexing.LINKS.

Returns:: Improved estimates of all LTT derivatives.
Return type:: DatasetLike of shape (time_sampling.size, 6)

property ltts: DatasetLike[source]¶

Improved estimates of all LTTs [s].

Links are ordered according to lisaconstants.indexing.LINKS.

Returns:: Improved estimates of all LTTs.
Return type:: DatasetLike of shape (time_sampling.size, 6)

property time_sampling: UniformTimeSampling[source]¶: Uniform time sampling of LTT observables.

class mojito.reader.Orbits(groups)[source]¶

Provides access to spacecraft orbits stored in Mojito L1 files.

No consistency checks are performed across groups. In particular, we do not check that orbit estimates are identical across groups (we only return one). Use the check_consistent() method to check for consistency.

Parameters:: groups (list[Group]) – List of HDF5 groups containing the orbits datasets.

groups¶: List of HDF5 groups containing the orbits datasets.

DATASETS¶: List of dataset names expected in each group.

GROUPS¶: List of group names expected in each group.

Raises:: ValueError – If there are no groups.

check_consistent(*, quick=False, chunk=100000)[source]¶

Check if time samplings and orbit estimates are equal across groups.

This can be an expensive operation, since orbit estimates need to be read from disk. If you only want to check that time samplings are consistent across groups, set quick=True to only check time samplings.

To limit memory usage when checking orbit estimates, you can set the chunk size to read and compare the orbit estimates in smaller chunks.

Parameters:

quick (bool, default: False) – Whether to only check time samplings for consistency, without checking that orbit estimates are identical across groups. This is a much faster check, since it does not require reading orbit estimates from disk, but it is less strict.
chunk (int, default: 100000) – Chunk size to use when checking orbit estimates for consistency. This limits memory usage when checking large datasets.

Raises:

ValueError – If time samplings are inconsistent across groups, or if orbit estimates are inconsistent across groups when quick=False.

Return type:

None

property is_complete: bool¶: Check if all groups and datasets are present in each group.

property position_1: DatasetLike[source]¶

Spacecraft 1 position in BCRS [m].

Returns:: Spacecraft 1 position.
Return type:: DatasetLike of shape (time_sampling.size, 3)

property position_2: DatasetLike[source]¶

Spacecraft 2 position in BCRS [m].

Returns:: Spacecraft 2 position.
Return type:: DatasetLike of shape (time_sampling.size, 3)

property position_3: DatasetLike[source]¶

Spacecraft 3 position in BCRS [m].

Returns:: Spacecraft 3 position.
Return type:: DatasetLike of shape (time_sampling.size, 3)

property positions: DatasetLike[source]¶

Positions of all spacecraft [m].

Spacecraft are ordered as lisaconstants.indexing.SPACECRAFT.

Returns:: Spacecraft positions. The second axis indexes the spacecraft, and the third axis indexes the Cartesian components.
Return type:: DatasetLike of shape (time_sampling.size, 3, 3)

property time_sampling: UniformTimeSampling[source]¶: Uniform time sampling of the orbits.

property velocities: DatasetLike[source]¶

Velocities of all spacecraft [m/s].

Spacecraft are ordered as lisaconstants.indexing.SPACECRAFT.

Returns:: Spacecraft velocities. The second axis indexes the spacecraft, and the third axis indexes the Cartesian components.
Return type:: DatasetLike of shape (time_sampling.size, 3, 3)

property velocity_1: DatasetLike[source]¶

Spacecraft 1 velocity in BCRS [m/s].

Returns:: Spacecraft 1 velocity.
Return type:: DatasetLike of shape (time_sampling.size, 3)

property velocity_2: DatasetLike[source]¶

Spacecraft 2 velocity in BCRS [m/s].

Returns:: Spacecraft 2 velocity.
Return type:: DatasetLike of shape (time_sampling.size, 3)

property velocity_3: DatasetLike[source]¶

Spacecraft 3 velocity in BCRS [m/s].

Returns:: Spacecraft 3 velocity.
Return type:: DatasetLike of shape (time_sampling.size, 3)

class mojito.reader.NoiseEstimates(groups)[source]¶

Provides access to noise estimates stored in Mojito L1 files.

No consistency checks are performed across groups. Use the check_consistent() method to check for consistency.

Parameters:: groups (list[Group]) – List of HDF5 groups containing the noise estimates datasets.

groups¶: List of HDF5 groups containing the noise estimates datasets.

DATASETS¶: List of dataset names expected in each group.

GROUPS¶: List of group names expected in each group.

Raises:: ValueError – If there are no groups.

property aet: DatasetLike[source]¶

Noise covariance estimate for TDI AET [Hz^2/Hz].

Returns:: Noise covariance estimate for TDI AET.
Return type:: DatasetLike of shape (time_sampling.size, freq_sampling.size, 3, 3)

check_consistent()[source]¶

Check if time and frequency samplings are equal across groups.

Return type:: None

property eta: DatasetLike[source]¶

Noise covariance estimate for single-link \(eta\) [Hz^2/Hz].

The single-link \(eta\) observables are ordered according to lisaconstants.indexing.MOSAS.

Returns:: Noise covariance estimate for single-link \(eta\).
Return type:: DatasetLike of shape (time_sampling.size, freq_sampling, 6, 6)

property freq_sampling: LogUniformFrequencySampling[source]¶: Log-uniform frequency sampling of the noise estimates.

property is_complete: bool¶: Check if all groups and datasets are present in each group.

property time_sampling: UniformTimeSampling[source]¶: Uniform time sampling of the noise estimates.

property xyz: DatasetLike[source]¶

Noise covariance estimate for TDI XYZ [Hz^2/Hz].

Returns:: Noise covariance estimate for TDI XYZ.
Return type:: DatasetLike of shape (time_sampling.size, freq_sampling.size, 3, 3)