def read_bgen(path: PathType, metafile_path: Optional[PathType]=None, sample_path: Optional[PathType]=None, chunks: Union[(str, int, Tuple[(int, int, int)])]='auto', lock: bool=False, persist: bool=True, contig_dtype: DType='str', gp_dtype: DType='float32') -> Dataset:
    'Read BGEN dataset.\n\n    Loads a single BGEN dataset as dask arrays within a Dataset\n    from a ``.bgen`` file.\n\n    Parameters\n    ----------\n    path\n        Path to BGEN file.\n    metafile_path\n        Path to companion index file used to determine BGEN byte offsets.\n        Defaults to ``path`` + ".metafile" if not provided.\n        This file is necessary for reading BGEN genotype probabilities and it will be\n        generated the first time the file is read if it does not already exist.\n        If it needs to be created, it can make the first call to this function\n        much slower than subsequent calls.\n    sample_path\n        Path to ``.sample`` file, by default None. This is used to fetch sample identifiers\n        and when provided it is preferred over sample identifiers embedded in the ``.bgen`` file.\n    chunks\n        Chunk size for genotype probability data (3 dimensions),\n        by default "auto".\n    lock\n        Whether or not to synchronize concurrent reads of\n        file blocks, by default False. This is passed through to\n        [dask.array.from_array](https://docs.dask.org/en/latest/array-api.html#dask.array.from_array).\n    persist\n        Whether or not to persist variant information in memory, by default True.\n        This is an important performance consideration as the metadata file for this data will\n        be read multiple times when False.\n    contig_dtype\n        Data type for contig names, by default "str".\n        This may also be an integer type (e.g. "int"), but will fail if any of the contig names\n        cannot be converted to integers.\n    gp_dtype\n        Data type for genotype probabilities, by default "float32".\n\n    Warnings\n    --------\n    Only bi-allelic, diploid BGEN files are currently supported.\n\n    Returns\n    -------\n    A dataset containing the following variables:\n\n    - :data:`sgkit.variables.variant_id_spec` (variants)\n    - :data:`sgkit.variables.variant_contig_spec` (variants)\n    - :data:`sgkit.variables.variant_position_spec` (variants)\n    - :data:`sgkit.variables.variant_allele_spec` (variants)\n    - :data:`sgkit.variables.sample_id_spec` (samples)\n    - :data:`sgkit.variables.call_dosage_spec` (variants, samples)\n    - :data:`sgkit.variables.call_dosage_mask_spec` (variants, samples)\n    - :data:`sgkit.variables.call_genotype_probability_spec` (variants, samples, genotypes)\n    - :data:`sgkit.variables.call_genotype_probability_mask_spec` (variants, samples, genotypes)\n\n    '
    if (isinstance(chunks, tuple) and (len(chunks) != 3)):
        raise ValueError(f'`chunks` must be tuple with 3 items, not {chunks}')
    if (not np.issubdtype(gp_dtype, np.floating)):
        raise ValueError(f'`gp_dtype` must be a floating point data type, not {gp_dtype}')
    if ((not np.issubdtype(contig_dtype, np.integer)) and (np.dtype(contig_dtype).kind not in {'U', 'S'})):
        raise ValueError(f'`contig_dtype` must be of string or int type, not {contig_dtype}')
    path = Path(path)
    sample_path = (Path(sample_path) if sample_path else path.with_suffix('.sample'))
    if sample_path.exists():
        sample_id = read_samples(sample_path).sample_id.values.astype('U')
    else:
        sample_id = _default_sample_ids(path)
    bgen_reader = BgenReader(path, metafile_path=metafile_path, dtype=gp_dtype)
    df = read_metafile(bgen_reader.metafile_path)
    if persist:
        df = df.persist()
    arrs = dataframe_to_dict(df, METAFILE_DTYPE)
    variant_id = arrs['id']
    variant_contig: ArrayLike = arrs['chrom'].astype(contig_dtype)
    (variant_contig, variant_contig_names) = encode_contigs(variant_contig)
    variant_contig_names = list(variant_contig_names)
    variant_position = arrs['pos']
    variant_allele = da.hstack((arrs['a1'][:, np.newaxis], arrs['a2'][:, np.newaxis]))
    call_genotype_probability = da.from_array(bgen_reader, chunks=chunks, lock=lock, fancy=False, asarray=False, name=f'{bgen_reader.name}:read_bgen:{path}')
    call_dosage = _to_dosage(call_genotype_probability)
    ds: Dataset = create_genotype_dosage_dataset(variant_contig_names=variant_contig_names, variant_contig=variant_contig, variant_position=variant_position, variant_allele=variant_allele, sample_id=sample_id, call_dosage=call_dosage, call_genotype_probability=call_genotype_probability, variant_id=variant_id)
    return ds
Read BGEN dataset.

Loads a single BGEN dataset as dask arrays within a Dataset
from a ``.bgen`` file.

Parameters
----------
path
    Path to BGEN file.
metafile_path
    Path to companion index file used to determine BGEN byte offsets.
    Defaults to ``path`` + ".metafile" if not provided.
    This file is necessary for reading BGEN genotype probabilities and it will be
    generated the first time the file is read if it does not already exist.
    If it needs to be created, it can make the first call to this function
    much slower than subsequent calls.
sample_path
    Path to ``.sample`` file, by default None. This is used to fetch sample identifiers
    and when provided it is preferred over sample identifiers embedded in the ``.bgen`` file.
chunks
    Chunk size for genotype probability data (3 dimensions),
    by default "auto".
lock
    Whether or not to synchronize concurrent reads of
    file blocks, by default False. This is passed through to
    [dask.array.from_array](https://docs.dask.org/en/latest/array-api.html#dask.array.from_array).
persist
    Whether or not to persist variant information in memory, by default True.
    This is an important performance consideration as the metadata file for this data will
    be read multiple times when False.
contig_dtype
    Data type for contig names, by default "str".
    This may also be an integer type (e.g. "int"), but will fail if any of the contig names
    cannot be converted to integers.
gp_dtype
    Data type for genotype probabilities, by default "float32".

Warnings
--------
Only bi-allelic, diploid BGEN files are currently supported.

Returns
-------
A dataset containing the following variables:

- :data:`sgkit.variables.variant_id_spec` (variants)
- :data:`sgkit.variables.variant_contig_spec` (variants)
- :data:`sgkit.variables.variant_position_spec` (variants)
- :data:`sgkit.variables.variant_allele_spec` (variants)
- :data:`sgkit.variables.sample_id_spec` (samples)
- :data:`sgkit.variables.call_dosage_spec` (variants, samples)
- :data:`sgkit.variables.call_dosage_mask_spec` (variants, samples)
- :data:`sgkit.variables.call_genotype_probability_spec` (variants, samples, genotypes)
- :data:`sgkit.variables.call_genotype_probability_mask_spec` (variants, samples, genotypes)
def read_bgen(path: PathType, metafile_path: Optional[PathType]=None, sample_path: Optional[PathType]=None, chunks: Union[(str, int, Tuple[(int, int, int)])]='auto', lock: bool=False, persist: bool=True, contig_dtype: DType='str', gp_dtype: DType='float32') -> Dataset:
    'Read BGEN dataset.\n\n    Loads a single BGEN dataset as dask arrays within a Dataset\n    from a ``.bgen`` file.\n\n    Parameters\n    ----------\n    path\n        Path to BGEN file.\n    metafile_path\n        Path to companion index file used to determine BGEN byte offsets.\n        Defaults to ``path`` + ".metafile" if not provided.\n        This file is necessary for reading BGEN genotype probabilities and it will be\n        generated the first time the file is read if it does not already exist.\n        If it needs to be created, it can make the first call to this function\n        much slower than subsequent calls.\n    sample_path\n        Path to ``.sample`` file, by default None. This is used to fetch sample identifiers\n        and when provided it is preferred over sample identifiers embedded in the ``.bgen`` file.\n    chunks\n        Chunk size for genotype probability data (3 dimensions),\n        by default "auto".\n    lock\n        Whether or not to synchronize concurrent reads of\n        file blocks, by default False. This is passed through to\n        [dask.array.from_array](https://docs.dask.org/en/latest/array-api.html#dask.array.from_array).\n    persist\n        Whether or not to persist variant information in memory, by default True.\n        This is an important performance consideration as the metadata file for this data will\n        be read multiple times when False.\n    contig_dtype\n        Data type for contig names, by default "str".\n        This may also be an integer type (e.g. "int"), but will fail if any of the contig names\n        cannot be converted to integers.\n    gp_dtype\n        Data type for genotype probabilities, by default "float32".\n\n    Warnings\n    --------\n    Only bi-allelic, diploid BGEN files are currently supported.\n\n    Returns\n    -------\n    A dataset containing the following variables:\n\n    - :data:`sgkit.variables.variant_id_spec` (variants)\n    - :data:`sgkit.variables.variant_contig_spec` (variants)\n    - :data:`sgkit.variables.variant_position_spec` (variants)\n    - :data:`sgkit.variables.variant_allele_spec` (variants)\n    - :data:`sgkit.variables.sample_id_spec` (samples)\n    - :data:`sgkit.variables.call_dosage_spec` (variants, samples)\n    - :data:`sgkit.variables.call_dosage_mask_spec` (variants, samples)\n    - :data:`sgkit.variables.call_genotype_probability_spec` (variants, samples, genotypes)\n    - :data:`sgkit.variables.call_genotype_probability_mask_spec` (variants, samples, genotypes)\n\n    '
    if (isinstance(chunks, tuple) and (len(chunks) != 3)):
        raise ValueError(f'`chunks` must be tuple with 3 items, not {chunks}')
    if (not np.issubdtype(gp_dtype, np.floating)):
        raise ValueError(f'`gp_dtype` must be a floating point data type, not {gp_dtype}')
    if ((not np.issubdtype(contig_dtype, np.integer)) and (np.dtype(contig_dtype).kind not in {'U', 'S'})):
        raise ValueError(f'`contig_dtype` must be of string or int type, not {contig_dtype}')
    path = Path(path)
    sample_path = (Path(sample_path) if sample_path else path.with_suffix('.sample'))
    if sample_path.exists():
        sample_id = read_samples(sample_path).sample_id.values.astype('U')
    else:
        sample_id = _default_sample_ids(path)
    bgen_reader = BgenReader(path, metafile_path=metafile_path, dtype=gp_dtype)
    df = read_metafile(bgen_reader.metafile_path)
    if persist:
        df = df.persist()
    arrs = dataframe_to_dict(df, METAFILE_DTYPE)
    variant_id = arrs['id']
    variant_contig: ArrayLike = arrs['chrom'].astype(contig_dtype)
    (variant_contig, variant_contig_names) = encode_contigs(variant_contig)
    variant_contig_names = list(variant_contig_names)
    variant_position = arrs['pos']
    variant_allele = da.hstack((arrs['a1'][:, np.newaxis], arrs['a2'][:, np.newaxis]))
    call_genotype_probability = da.from_array(bgen_reader, chunks=chunks, lock=lock, fancy=False, asarray=False, name=f'{bgen_reader.name}:read_bgen:{path}')
    call_dosage = _to_dosage(call_genotype_probability)
    ds: Dataset = create_genotype_dosage_dataset(variant_contig_names=variant_contig_names, variant_contig=variant_contig, variant_position=variant_position, variant_allele=variant_allele, sample_id=sample_id, call_dosage=call_dosage, call_genotype_probability=call_genotype_probability, variant_id=variant_id)
    return ds