### Read BED file from HTTP using local metadata files (Python)

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/cloud_urls.rst

Demonstrates reading a BED file from an HTTP URL while using locally downloaded .fam and .bim metadata files. This approach provides faster access to metadata and the BED file itself. The `sample_file` function is used to get paths to example metadata files.

```python
>>> from bed_reader import open_bed, sample_file
>>> import numpy as np
>>> # For this example, assume 'synthetic_v1_chr-10.fam' and 'synthetic_v1_chr-10.bim' are already downloaded
>>> # and 'local_fam_file' and 'local_bim_file' variables are set to their local file paths.
>>> local_fam_file = sample_file("synthetic_v1_chr-10.fam")
>>> local_bim_file = sample_file("synthetic_v1_chr-10.bim")
>>> with open_bed(
...     "https://www.ebi.ac.uk/biostudies/files/S-BSST936/genotypes/synthetic_v1_chr-10.bed",
...     fam_filepath=local_fam_file,
...     bim_filepath=local_bim_file,
...     skip_format_check=True,
... ) as bed:
...     print(f"iid_count={bed.iid_count:_}, sid_count={bed.sid_count:_}")
...     print(f"iid={bed.iid[:5]}...")
...     print(f"sid={bed.sid[:5]}...")
```

--------------------------------

### Install bed-reader (Bash)

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/index.rst

Installs the bed-reader package. The full version includes optional dependencies for samples and sparse data, while the minimal version depends only on numpy.

```bash
pip install bed-reader[samples,sparse]
pip install bed-reader
```

--------------------------------

### Read Cloud Files with ReadOptions

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/options_etc.md

Shows how to read data from a file using ReadOptions builder. This example demonstrates reading from a local file treated as a cloud source using EMPTY_OPTIONS.

```rust
use ndarray as nd;
use bed_reader::{BedCloud, ReadOptions, assert_eq_nan, sample_url, EMPTY_OPTIONS};

let url = sample_url("small.bed")?;
let options = EMPTY_OPTIONS;
let mut bed_cloud = BedCloud::new_with_options(url, options).await?;
let val = ReadOptions::builder().sid_index(2).f64().read_cloud(&mut bed_cloud).await?;
assert_eq_nan(&val, &nd::array![[f64::NAN], [f64::NAN], [2.0]]);
```

--------------------------------

### Read genomic data from HTTP URL

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/cloud_urls_etc.md

Demonstrates how to initialize a BedCloud connection from a URL and read the entire dataset into an ndarray to calculate missing values.

```rust
use ndarray as nd;
use bed_reader::{BedCloud};

let url = "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed";
let mut bed_cloud = BedCloud::new(url).await?;
let val: nd::Array2<f32> = bed_cloud.read().await?;
let missing_count = val.iter().filter(|x| x.is_nan()).count();
let missing_fraction = missing_count as f32 / val.len() as f32;
println!("{missing_fraction:.2}");
```

--------------------------------

### Read Data from AWS S3 using bed-reader

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/cloud_urls.rst

Illustrates how to read data from an AWS S3 bucket using the `bed-reader` library. This involves specifying the S3 URL and providing necessary cloud options such as `aws_region`, `aws_access_key_id`, and `aws_secret_access_key`. The example retrieves credentials from a local AWS configuration file. Dependencies include `os`, `configparser`, and `bed_reader`.

```python
import os
import configparser
from bed_reader import open_bed

config = configparser.ConfigParser()
_ = config.read(os.path.expanduser("~/.aws/credentials"))

cloud_options = {
    "aws_region": "us-west-2",
    "aws_access_key_id": config["default"].get("aws_access_key_id"),
    "aws_secret_access_key": config["default"].get("aws_secret_access_key"),
}

with open_bed("s3://bedreader/v1/toydata.5chrom.bed", cloud_options=cloud_options) as bed:
    val = bed.read(dtype="int8")
    print(val.shape)
```

--------------------------------

### Read BED file from HTTP URL and calculate missing values (Python)

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/cloud_urls.rst

Reads an entire BED file from a public HTTP URL and calculates the fraction of missing values. This example is suitable for small to medium-sized files. It utilizes the `open_bed` function from the `bed_reader` package.

```python
>>> import numpy as np
>>> from bed_reader import open_bed
>>> with open_bed("https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed") as bed:
...     val = bed.read()
...     missing_count = np.isnan(val).sum()
...     missing_fraction = missing_count / val.size
...     missing_fraction  # doctest: +ELLIPSIS
np.float64(0.16666666666666666)
```

--------------------------------

### Read Data from Local File using bed-reader

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/cloud_urls.rst

Demonstrates how to open and read data from a local BED file using a file URI. It shows the process of constructing the file URI and then using `open_bed` to read a specific column. Dependencies include `numpy`, `bed_reader`, `urllib.parse`, and `pathlib`.

```python
import numpy as np
from bed_reader import open_bed, sample_file
from urllib.parse import urljoin
from pathlib import Path
file_name = str(sample_file("small.bed"))
print(f"file name: {file_name}")   # doctest: +ELLIPSIS
url = urljoin("file:", Path(file_name).as_uri())
print(f"url: {url}") # doctest: +ELLIPSIS
with open_bed(url) as bed:
    val = bed.read(index=np.s_[:, 2], dtype=np.float64)
    print(val)
```

--------------------------------

### Read Local File URL with BedCloud

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/cloud_urls_etc.md

Demonstrates how to construct a file URL for local files using `abs_path_to_url_string` and read data using `BedCloud`. It requires the `tokio` feature and uses `ReadOptions` to specify read parameters.

```rust
use ndarray as nd;
use bed_reader::{BedCloud, ReadOptions, assert_eq_nan, sample_bed_file};
use cloud_file::abs_path_to_url_string;

# #[cfg(feature = "tokio")] Runtime::new().unwrap().block_on(async { // '#' needed for doc test
let file_name = sample_bed_file("small.bed")?;
println!("{file_name:?}"); // For example, "C:\\Users\\carlk\\AppData\\Local\\fastlmm\\bed-reader\\cache\\small.bed"
let url: String = abs_path_to_url_string(file_name)?;
println!("{url:?}"); // For example, "file:///C:/Users/carlk/AppData/Local/bed_reader/bed_reader/Cache/small.bed"

let mut bed_cloud = BedCloud::new(url).await?;
let val = ReadOptions::builder().sid_index(2).f64().read_cloud(&mut bed_cloud).await?;
assert_eq_nan(&val, &nd::array![[f64::NAN], [f64::NAN], [2.0]]);
# Ok::<(), Box<dyn std::error::Error>>(()) }).unwrap();  // '#' needed for doctest
# #[cfg(feature = "tokio")] use {tokio::runtime::Runtime, bed_reader::BedErrorPlus}; // '#' needed for doctest

```

--------------------------------

### Read filtered genomic data with custom configuration

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/cloud_urls_etc.md

Shows how to configure a BedCloud connection with a custom timeout and skip early header checks. It also demonstrates filtering data by chromosome and reading specific subsets.

```rust
use ndarray::{self as nd, s};
use bed_reader::{BedCloud, ReadOptions};
use std::collections::BTreeSet;

let mut bed_cloud = BedCloud::builder_with_options(
    "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/toydata.5chrom.bed",
    [("timeout", "100s")],
)?.skip_early_check().build().await?;

let val = ReadOptions::builder()
    .sid_index(bed_cloud.chromosome().await?.map(|elem| elem == "5"))
    .f32()
    .read_cloud(&mut bed_cloud)
    .await?;
```

--------------------------------

### Read AWS S3 File with BedCloud

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/cloud_urls_etc.md

Shows how to read data from an AWS S3 bucket using `BedCloud`. It requires AWS credentials to be configured (e.g., in `~/.aws/credentials`) and specifies AWS region and authentication details via options. The `tokio` feature is required.

```rust
use bed_reader::{BedCloud,BedErrorPlus};
use rusoto_credential::{CredentialsError, ProfileProvider, ProvideAwsCredentials};

# #[cfg(feature = "tokio")] Runtime::new().unwrap().block_on(async { // '#' needed for doc test
// Read my AWS credentials from file ~/.aws/credentials
let credentials = if let Ok(provider) = ProfileProvider::new() {
    provider.credentials().await
} else {
    Err(CredentialsError::new("No credentials found"))
};

let Ok(credentials) = credentials else {
    eprintln!("Skipping test because no AWS credentials found");
    return Ok(());
};

let url = "s3://bedreader/v1/toydata.5chrom.bed";
let options = [
    ("aws_region", "us-west-2"),
    ("aws_access_key_id", credentials.aws_access_key_id()),
    ("aws_secret_access_key", credentials.aws_secret_access_key()),
];

let mut bed_cloud = BedCloud::new_with_options(url, options).await?;
let val = bed_cloud.read::<i8>().await?;
assert_eq!(val.shape(), &[500, 10_000]);
# Ok::<(), Box<dyn std::error::Error>>(()) }).unwrap();
# #[cfg(feature = "tokio")] use tokio::runtime::Runtime;

```

--------------------------------

### Read Genotype Data from BED Files

Source: https://github.com/fastlmm/bed-reader/blob/master/README-rust.md

Demonstrates how to initialize a Bed reader and load genotype data into an ndarray. This example shows reading the entire dataset and verifying the output against expected values.

```rust
use ndarray as nd;
use bed_reader::{Bed, ReadOptions, assert_eq_nan, sample_bed_file};

let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder().f64().read(&mut bed)?;

assert_eq_nan(
    &val,
    &nd::array![
        [1.0, 0.0, f64::NAN, 0.0],
        [2.0, 0.0, f64::NAN, 2.0],
        [0.0, 1.0, 2.0, 0.0]
    ],
);
```

--------------------------------

### Install bed-reader via Cargo

Source: https://github.com/fastlmm/bed-reader/blob/master/README-rust.md

Instructions for adding the bed-reader dependency to a Rust project. The full version supports both local and cloud files, while the minimal version is restricted to local files.

```bash
cargo add bed-reader
```

```bash
cargo add bed-reader --no-default-features
```

--------------------------------

### Create individual-major BED file

Source: https://github.com/fastlmm/bed-reader/blob/master/bed_reader/tests/benchmark/bench2.ipynb

Generates a large BED file in individual-major format. This example demonstrates writing data row-by-row and includes progress tracking for long-running operations.

```python
import time
import numpy as np

iid_count = 250_000
sid_count = 1_000_000
file_path = ssd_path / f"{iid_count}x{sid_count}mode0.bed"
snp_row = np.array(range(sid_count)) % 3
snp_row = snp_row.astype(np.uint8)

start_time = time.time()
with create_bed(file_path, iid_count=iid_count, sid_count=sid_count, major="individual") as bed_writer:
    for iid_index in range(iid_count):
        bed_writer.write(snp_row)
        snp_row[iid_index] = (snp_row[iid_index] + 1) % 3
```

--------------------------------

### Read specific SNP from large cloud files

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/cloud_urls_etc.md

Optimizes reading from large files (e.g., 91GB) by providing explicit sample and variant counts and skipping early header checks to perform targeted data retrieval.

```rust
use ndarray as nd;
use bed_reader::{BedCloud, ReadOptions, EMPTY_OPTIONS};

let mut bed_cloud = BedCloud::builder(
        "https://www.ebi.ac.uk/biostudies/files/S-BSST936/genotypes/synthetic_v1_chr-10.bed")?
    .skip_early_check()
    .iid_count(1_008_000)
    .sid_count(361_561)
    .build()
    .await?;
let val = ReadOptions::builder()
    .sid_index(100_000)
    .f32()
    .read_cloud(&mut bed_cloud)
    .await?;
```

--------------------------------

### Read BED file from HTTP with timeout and skip format check (Python)

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/cloud_urls.rst

Reads a BED file from an HTTP URL with a specified timeout and skips the initial format check for faster loading. It demonstrates accessing sample IDs (iids), variant IDs (sids), chromosome information, and reading data for a specific chromosome. This is useful for medium to large files where metadata might take longer to download.

```python
>>> import numpy as np
>>> from bed_reader import open_bed
>>> with open_bed(
...     "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/toydata.5chrom.bed",
...     cloud_options={"timeout": "100s"},
...     skip_format_check=True,
...     ) as bed:
...     bed.iid[:5]
...     bed.sid[:5]
...     np.unique(bed.chromosome)
...     val = bed.read(index=np.s_[:, bed.chromosome == "5"])
...     val.shape
array(['per0', 'per1', 'per2', 'per3', 'per4'], dtype='<U11')
array(['null_0', 'null_1', 'null_2', 'null_3', 'null_4'], dtype='<U9')
array(['1', '2', '3', '4', '5'], dtype='<U9')
(500, 440)
```

--------------------------------

### Read Genomic Data from BED File

Source: https://github.com/fastlmm/bed-reader/blob/master/README.md

Demonstrates how to open a BED file using `open_bed` and read all its genomic data. The `sample_file` function is used to access a local sample BED file. The read data is stored in a NumPy array. Ensure the 'bed-reader' package is installed.

```python
import numpy as np
from bed_reader import open_bed, sample_file

file_name = sample_file("small.bed")
bed = open_bed(file_name)
val = bed.read()
print(val)
del bed
```

--------------------------------

### Read specific SNP data from a large BED file with metadata counts (Python)

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/cloud_urls.rst

Reads data for a single SNP from a very large BED file (91 GB) by providing the exact counts for individuals (iid_count) and SNPs (sid_count). This allows for efficient reading of specific data points without loading the entire file. It also includes a timeout for cloud access and skips the format check.

```python
>>> import numpy as np
>>> from bed_reader import open_bed
>>> with open_bed(
...     "https://www.ebi.ac.uk/biostudies/files/S-BSST936/genotypes/synthetic_v1_chr-10.bed",
...     cloud_options={"timeout": "100s"},
...     skip_format_check=True,
...     iid_count=1_008_000,
...     sid_count=361_561,
...     ) as bed:
...     val = bed.read(index=np.s_[:, 100_000], dtype=np.float32)
...     np.mean(val) # doctest: +ELLIPSIS
np.float32(0.03391369)
```

--------------------------------

### Read Genomic Data from Cloud Storage

Source: https://github.com/fastlmm/bed-reader/blob/master/README.md

Demonstrates opening and reading data from a BED file hosted on a cloud URL (GitHubusercontent in this case). The `open_bed` function directly accepts URLs. This example reads data for a single SNP at index position 2 and specifies the data type as float64. Requires 'bed-reader'.

```python
from bed_reader import open_bed

with open_bed("https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed") as bed:
    val = bed.read(index=np.s_[:,2], dtype="float64")
    print(val)
```

--------------------------------

### Read Specific Slices of Genomic Data

Source: https://github.com/fastlmm/bed-reader/blob/master/README.md

Shows how to read specific portions of a BED file by providing an index to the `read` method. This example reads every second individual and SNPs from index 20 to 30. The `np.s_` object is used for slicing. This requires the 'bed-reader' package.

```python
import numpy as np
from bed_reader import open_bed, sample_file

file_name2 = sample_file("some_missing.bed")
bed2 = open_bed(file_name2)
val2 = bed2.read(index=np.s_[::2,20:30])
print(val2.shape)
del bed2
```

--------------------------------

### Utilize helper utilities

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Demonstrates the use of helper functions for accessing sample data, generating file URLs, and managing temporary paths for testing.

```python
from bed_reader import sample_file, sample_url, tmp_path, open_bed, to_bed

local_path = sample_file("small.bed")
file_url = sample_url("small.bed")
temp_dir = tmp_path()

output_file = tmp_path() / "test_output.bed"
to_bed(output_file, [[1, 0], [2, 1], [0, 2]])
```

--------------------------------

### Configure Cloud Storage Access with BedCloud

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/options_etc.md

Demonstrates how to initialize a BedCloud instance with authentication credentials for AWS S3. It uses the BedCloud::new_with_options method to pass required region and key information.

```rust
use bed_reader::{BedCloud,BedErrorPlus};
use rusoto_credential::{CredentialsError, ProfileProvider, ProvideAwsCredentials};

let credentials = if let Ok(provider) = ProfileProvider::new() {
    provider.credentials().await
} else {
    Err(CredentialsError::new("No credentials found"))
};

let Ok(credentials) = credentials else {
    eprintln!("Skipping test because no AWS credentials found");
    return Ok(());
};

let url = "s3://bedreader/v1/toydata.5chrom.bed";
let options = [
    ("aws_region", "us-west-2"),
    ("aws_access_key_id", credentials.aws_access_key_id()),
    ("aws_secret_access_key", credentials.aws_secret_access_key()),
];

let mut bed_cloud = BedCloud::new_with_options(url, options).await?;
let val = bed_cloud.read::<i8>().await?;
assert_eq!(val.shape(), &[500, 10_000]);
```

--------------------------------

### Open and Read PLINK BED Files with open_bed (Python)

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Demonstrates how to open a PLINK BED file using the `open_bed` function, access its metadata (individuals, SNPs, chromosomes), and read all genotype data. It also shows the recommended usage of a context manager for automatic resource cleanup. Dependencies include `numpy` and `bed_reader`.

```python
import numpy as np
from bed_reader import open_bed, sample_file

# Open a local BED file and read all data
file_name = sample_file("small.bed")
bed = open_bed(file_name)

# Access metadata properties
print(f"Individuals: {bed.iid}")        # ['iid1' 'iid2' 'iid3']
print(f"SNP IDs: {bed.sid}")            # ['sid1' 'sid2' 'sid3' 'sid4']
print(f"Chromosomes: {bed.chromosome}") # ['1' '1' '5' 'Y']
print(f"Shape: {bed.shape}")            # (3, 4)

# Read all genotype data (0, 1, 2, or NaN for missing)
val = bed.read()
print(val)
# [[ 1.  0. nan  0.]
#  [ 2.  0. nan  2.]
#  [ 0.  1.  2.  0.]]

del bed  # Clean up

# Using context manager (recommended)
with open_bed(file_name) as bed:
    data = bed.read()
    print(f"Data shape: {data.shape}")
```

--------------------------------

### Initialize BED file path

Source: https://github.com/fastlmm/bed-reader/blob/master/bed_reader/tests/benchmark/bench2.ipynb

Sets up the file path for BED file operations using pathlib. It is recommended to use a fast drive for large file generation.

```python
from pathlib import Path
from bed_reader import create_bed, open_bed

ssd_path = Path("m:/deldir/bench2")
```

--------------------------------

### Access Metadata from .fam and .bim Files

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Shows how to access individual (sample) metadata from the .fam file and SNP (variant) metadata from the .bim file as numpy arrays. This includes properties like family IDs, individual IDs, sex, phenotype, chromosome, SNP IDs, and allele information.

```python
from bed_reader import open_bed, sample_file

file_name = sample_file("small.bed")

with open_bed(file_name) as bed:
    # Individual (sample) properties from .fam file
    print(f"Family IDs: {bed.fid}")           # ['fid1' 'fid1' 'fid2']
    print(f"Individual IDs: {bed.iid}")       # ['iid1' 'iid2' 'iid3']
    print(f"Father IDs: {bed.father}")        # ['iid23' 'iid23' 'iid22']
    print(f"Mother IDs: {bed.mother}")        # ['iid34' 'iid34' 'iid33']
    print(f"Sex (0=unknown,1=male,2=female): {bed.sex}")  # [1 2 0]
    print(f"Phenotype: {bed.pheno}")          # ['red' 'red' 'blue']

    # SNP (variant) properties from .bim file
    print(f"Chromosomes: {bed.chromosome}")   # ['1' '1' '5' 'Y']
    print(f"SNP IDs: {bed.sid}")              # ['sid1' 'sid2' 'sid3' 'sid4']
    print(f"cM positions: {bed.cm_position}") # [ 100.4 2000.5 4000.7 7000.9]
    print(f"bp positions: {bed.bp_position}") # [   1  100 1000 1004]
    print(f"Allele 1: {bed.allele_1}")        # ['A' 'T' 'A' 'T']
    print(f"Allele 2: {bed.allele_2}")        # ['A' 'C' 'C' 'G']

    # Counts
    print(f"Individual count: {bed.iid_count}")  # 3
    print(f"SNP count: {bed.sid_count}")         # 4
    print(f"Shape: {bed.shape}")                 # (3, 4)

    # All properties as dictionary
    props = bed.properties
    print(f"Number of properties: {len(props)}")  # 12
```

--------------------------------

### Write BED files from NumPy arrays

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Demonstrates how to export NumPy arrays to BED format using the to_bed function, including handling missing values and specifying major order.

```python
import numpy as np
from bed_reader import to_bed, tmp_path

# Write with integer data (missing = -127)
int_data = np.array([[1, 0, -127, 0], [2, 0, -127, 2], [0, 1, 2, 0]])
to_bed(tmp_path() / "int_example.bed", int_data)

# Write in individual-major mode
to_bed(tmp_path() / "ind_major.bed", int_data, major="individual")
```

--------------------------------

### Specify Data Types and Memory Layout with read()

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Demonstrates how to use the `read()` method to specify output data types (float32, float64, int8) and memory layouts (Fortran/column-major 'F', C/row-major 'C') when reading BED files. This allows for control over precision and memory efficiency.

```python
import numpy as np
from bed_reader import open_bed, sample_file

file_name = sample_file("small.bed")

with open_bed(file_name) as bed:
    # Default: float32, Fortran order (SNP-major)
    val_f32 = bed.read()
    print(f"dtype: {val_f32.dtype}, F-contiguous: {val_f32.flags['F_CONTIGUOUS']}")
    # dtype: float32, F-contiguous: True

    # Read as float64 for higher precision
    val_f64 = bed.read(dtype="float64")
    print(f"dtype: {val_f64.dtype}")
    # dtype: float64

    # Read as int8 (missing values represented as -127)
    val_i8 = bed.read(dtype="int8")
    print(val_i8)
    # [[   1    0 -127    0]
    #  [   2    0 -127    2]
    #  [   0    1    2    0]]

    # Read in C order (row-major, individual-major)
    val_c = bed.read(order="C")
    print(f"C-contiguous: {val_c.flags['C_CONTIGUOUS']}")
    # C-contiguous: True
```

--------------------------------

### Customize metadata and read properties

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Explains how to override metadata during file opening and optimize performance by skipping the reading of specific properties.

```python
from bed_reader import open_bed, sample_file

file_name = sample_file("small.bed")

# Replace individual IDs
bed = open_bed(file_name, properties={"iid": ["sample1", "sample2", "sample3"]})

# Skip reading certain properties
bed = open_bed(file_name, properties={"father": None, "mother": None})

# Provide counts to avoid reading .fam/.bim files
with open_bed(file_name, iid_count=3, sid_count=4) as bed:
    data = bed.read()
```

--------------------------------

### Stream large files with create_bed

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Shows how to write large BED files incrementally using the create_bed context manager to minimize memory usage. Supports both SNP-by-SNP and individual-by-individual writing modes.

```python
import numpy as np
from bed_reader import create_bed, open_bed, tmp_path

output_file = tmp_path() / "large_example.bed"
properties = {"iid": ["ind1", "ind2", "ind3"], "sid": ["rs001", "rs002", "rs003", "rs004"]}

# Write SNP-by-SNP
with create_bed(output_file, iid_count=3, sid_count=4, properties=properties) as writer:
    writer.write([1.0, 2.0, 0.0])
    writer.write([0.0, 0.0, 1.0])
    writer.write([np.nan, np.nan, 2.0])
    writer.write([0.0, 2.0, 0.0])
```

--------------------------------

### Read PLINK BED Files from Cloud Storage (Python)

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Demonstrates how to open and read PLINK BED files directly from cloud storage URLs (AWS S3, Azure Blob, Google Cloud Storage) using the `open_bed` function. Supports the same indexing and slicing capabilities as local files. Cloud-specific options like timeouts can be configured. Requires `numpy` and `bed_reader`.

```python
import numpy as np
from bed_reader import open_bed

# Read from a public URL
url = "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed"

with open_bed(url) as bed:
    # Read a single SNP at index 2
    val = bed.read(np.s_[:, 2], dtype="float64")
    print(val)
    # [[nan]
    #  [nan]
    #  [ 2.]]

# With cloud options (e.g., timeout configuration)
with open_bed(url, cloud_options={"timeout": "30s"}) as bed:
    data = bed.read()
    print(f"Shape: {data.shape}")

# For AWS S3 (requires credentials)
# s3_url = "s3://bucket-name/path/to/file.bed"
# with open_bed(s3_url, cloud_options={"region": "us-west-2"}) as bed:
#     data = bed.read()

# For Azure Blob Storage
# azure_url = "az://container/path/to/file.bed"
# with open_bed(azure_url, cloud_options={"account_name": "myaccount"}) as bed:
#     data = bed.read()
```

--------------------------------

### Write BED Files with to_bed()

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Illustrates how to use the `to_bed()` function to write a 2D numpy array and associated metadata into the PLINK BED file format. This process creates the .bed, .fam, and .bim files, allowing for data export and compatibility with other tools.

```python
import numpy as np
from bed_reader import to_bed, open_bed, tmp_path

output_file = tmp_path() / "example.bed"

# Create genotype data (0, 1, 2, or np.nan for missing)
val = np.array([
    [1.0, 0.0, np.nan, 0.0],
    [2.0, 0.0, np.nan, 2.0],
    [0.0, 1.0, 2.0, 0.0]
])

# Define all metadata properties
properties = {
    "fid": ["fam1", "fam1", "fam2"],
    "iid": ["ind1", "ind2", "ind3"],
    "father": ["0", "0", "0"],
    "mother": ["0", "0", "0"],
    "sex": [1, 2, 0],
    "pheno": ["control", "control", "case"],
    "chromosome": ["1", "1", "5", "Y"],
    "sid": ["rs001", "rs002", "rs003", "rs004"],
    "cm_position": [0.0, 0.0, 0.0, 0.0],
    "bp_position": [1000, 2000, 3000, 4000],
    "allele_1": ["A", "G", "C", "T"],
    "allele_2": ["T", "A", "G", "C"],
}

# Write to BED format
to_bed(output_file, val, properties=properties)

# Verify by reading back
with open_bed(output_file) as bed:
    print(f"Shape: {bed.shape}")      # (3, 4)
    print(f"IIDs: {bed.iid}")         # ['ind1' 'ind2' 'ind3']
    print(f"SIDs: {bed.sid}")         # ['rs001' 'rs002' 'rs003' 'rs004']
    data = bed.read()
    print(data)
```

--------------------------------

### Read remote BED file data using BedCloud

Source: https://github.com/fastlmm/bed-reader/blob/master/README-rust.md

Demonstrates how to initialize a BedCloud instance from a URL and read specific genomic data using ReadOptions. This requires the 'tokio' feature enabled and performs asynchronous I/O operations.

```rust
let url = "https://raw.githubusercontent.com/fastlmm/bed-sample-files/main/small.bed";
let mut bed_cloud = BedCloud::new(url).await?;
let val = ReadOptions::builder().sid_index(2).f64().read_cloud(&mut bed_cloud).await?;
assert_eq_nan(&val, &nd::array![[f64::NAN], [f64::NAN], [2.0]]);
```

--------------------------------

### Read Sparse Data with read_sparse()

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Explains how to use `read_sparse()` to efficiently read BED files with a high proportion of zero values, returning scipy sparse matrices. This method supports specifying data types and output formats (CSC or CSR) to minimize memory usage.

```python
import numpy as np
from bed_reader import open_bed, sample_file

# Requires: pip install bed-reader[sparse]
file_name = sample_file("sparse.bed")

with open_bed(file_name) as bed:
    print(f"Shape: {bed.shape}")  # (10, 20)

    # Read as sparse CSC matrix (column-major, default)
    sparse_csc = bed.read_sparse(dtype="int8")
    print(f"Nonzero values: {sparse_csc.data}")
    # Nonzero Values [1 2 2 1 1 1 1 1]
    print(f"Format: {sparse_csc.format}")  # csc

    # Read as sparse CSR matrix (row-major)
    sparse_csr = bed.read_sparse(dtype="int8", format="csr")
    print(f"Format: {sparse_csr.format}")  # csr

    # Read subset as sparse
    sparse_subset = bed.read_sparse(np.s_[:, 1:11], dtype="int8")
    print(f"Nonzero in subset: {sparse_subset.data}")
    # [1 2 2 1 1]

    # Control batch size for memory management
    sparse_batched = bed.read_sparse(dtype="int8", batch_size=5000)
```

--------------------------------

### Control multi-threaded I/O

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Provides methods to configure thread counts for BED file operations, including environment variables and per-operation parameters.

```python
import os
from bed_reader import open_bed, get_num_threads, sample_file

# Set via environment variable
os.environ["PST_NUM_THREADS"] = "4"

# Set per-file or per-read
file_name = sample_file("small.bed")
with open_bed(file_name, num_threads=2) as bed:
    data = bed.read(num_threads=1)
```

--------------------------------

### Override Metadata using BedBuilder

Source: https://github.com/fastlmm/bed-reader/blob/master/src/supplemental_documents/options_etc.md

Illustrates how to use the Bed builder to override file metadata, specifically replacing individual IDs (iid) when loading a BED file.

```rust
use bed_reader::{Bed, sample_bed_file};
let file_name = sample_bed_file("small.bed")?;
let mut bed = Bed::builder(file_name)
   .iid(["sample1", "sample2", "sample3"])
   .build()?;
println!("{:?}", bed.iid()?);
```

--------------------------------

### Filter Data by Metadata and Chromosome

Source: https://github.com/fastlmm/bed-reader/blob/master/README-rust.md

Demonstrates accessing file metadata such as sample IDs, SNP IDs, and chromosome information, and using that metadata to filter data during the read process.

```rust
use ndarray::s;
use bed_reader::{Bed, ReadOptions, sample_bed_file};
use std::collections::HashSet;

let file_name = sample_bed_file("some_missing.bed")?;
let mut bed = Bed::new(file_name)?;

let val = ReadOptions::builder()
    .sid_index(bed.chromosome()?.map(|elem| elem == "5"))
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (100, 6));
```

--------------------------------

### Access Sample IDs, Variant IDs, and Chromosomes

Source: https://github.com/fastlmm/bed-reader/blob/master/README.md

Illustrates how to access metadata from a BED file, including individual IDs (`iid`), SNP IDs (`sid`), and unique chromosomes. It also shows how to read data for all SNPs on a specific chromosome. This uses the `with open_bed(...)` context manager for automatic resource management. Requires 'bed-reader'.

```python
import numpy as np
from bed_reader import open_bed

file_name2 = sample_file("some_missing.bed")
with open_bed(file_name2) as bed3:
    print(bed3.iid[:5])
    print(bed3.sid[:5])
    print(np.unique(bed3.chromosome))
    val3 = bed3.read(index=np.s_[:,bed3.chromosome=='5'])
    print(val3.shape)
```

--------------------------------

### Slice Samples and Variants

Source: https://github.com/fastlmm/bed-reader/blob/master/README-rust.md

Shows how to read specific subsets of data by applying indices to individuals (samples) and SNPs (variants) using ndarray slicing syntax.

```rust
use ndarray::s;
use bed_reader::{Bed, ReadOptions, sample_bed_file};

let file_name = sample_bed_file("some_missing.bed")?;
let mut bed = Bed::new(file_name)?;
let val = ReadOptions::builder()
    .iid_index(s![..;2])
    .sid_index(20..30)
    .f64()
    .read(&mut bed)?;

assert!(val.dim() == (50, 10));
```

--------------------------------

### Read Data Subsets from PLINK BED Files using Indexing (Python)

Source: https://context7.com/fastlmm/bed-reader/llms.txt

Illustrates how to use numpy-style indexing and slicing with the `bed.read()` method to efficiently retrieve specific subsets of individuals and SNPs from a PLINK BED file. Supports integer indexing, lists, slices, boolean arrays, and negative indexing. Requires `numpy` and `bed_reader`.

```python
import numpy as np
from bed_reader import open_bed, sample_file

file_name = sample_file("small.bed")
bed = open_bed(file_name)

# Read a single SNP (column) at index 2
snp_data = bed.read(np.s_[:, 2])
print(snp_data)
# [[nan]
#  [nan]
#  [ 2.]]

# Read specific SNPs by index list
subset = bed.read(np.s_[:, [2, 3, 0]])
print(subset)
# [[nan  0.  1.]
#  [nan  2.  2.]
#  [ 2.  0.  0.]]

# Read SNPs using slice (index 1 to 4)
slice_data = bed.read(np.s_[:, 1:4])
print(slice_data)
# [[ 0. nan  0.]
#  [ 0. nan  2.]
#  [ 1.  2.  0.]]

# Read first individual across all SNPs
individual = bed.read(np.s_[0, :])
print(individual)
# [[ 1.  0. nan  0.]]

# Read every 2nd individual
every_2nd = bed.read(np.s_[::2, :])
print(every_2nd)
# [[ 1.  0. nan  0.]
#  [ 0.  1.  2.  0.]]

# Filter by chromosome using boolean indexing
chrom5_data = bed.read(np.s_[:, bed.chromosome == '5'])
print(chrom5_data)
# [[nan]
#  [nan]
#  [ 2.]]

# Negative indexing: last and second-to-last individuals, last SNP
tail_data = bed.read(np.s_[[-1, -2], -1])
print(tail_data)
# [[0.]
#  [2.]]

del bed
```

--------------------------------

### Access .bed File Metadata and Read Chromosome Data (Python)

Source: https://github.com/fastlmm/bed-reader/blob/master/doc/source/index.rst

Opens a .bed file using a context manager to automatically handle closing. It prints the first 5 individual IDs, SNP IDs, unique chromosomes, and then reads all data for chromosome '5'.

```python
from bed_reader import open_bed
import numpy as np

file_name2 = sample_file("some_missing.bed")
with open_bed(file_name2) as bed3:
    print(bed3.iid[:5])
    print(bed3.sid[:5])
    print(np.unique(bed3.chromosome))
    val3 = bed3.read(index=np.s_[:,bed3.chromosome=='5'])
    print(val3.shape)
```

--------------------------------

### Read and validate BED data

Source: https://github.com/fastlmm/bed-reader/blob/master/bed_reader/tests/benchmark/bench2.ipynb

Opens an existing BED file and reads a subset of the data to verify integrity. The read method supports numpy-style slicing.

```python
with open_bed(file_path) as bed_reader:
    val = bed_reader.read(np.s_[:10, :10])
    print(bed_reader.shape)
```

--------------------------------

### Convert BED file format

Source: https://github.com/fastlmm/bed-reader/blob/master/bed_reader/tests/benchmark/bench2.ipynb

Transposes a BED file from individual-major to SNP-major format. It processes data in chunks to balance memory usage and execution speed.

```python
sid_at_a_time = 1000
file_path1 = ssd_path / f"{iid_count}x{sid_count}mode1.bed"

with create_bed(file_path1, iid_count=bed_reader.iid_count, sid_count=bed_reader.sid_count, properties=bed_reader.properties, major="SNP") as bed_writer:
    for sid_index in range(0, bed_reader.sid_count, sid_at_a_time):
        iid_column_by_chunk = bed_reader.read(np.s_[:, sid_index : sid_index + sid_at_a_time], dtype=np.int8)
        for iid_column in iid_column_by_chunk.T:
            bed_writer.write(iid_column)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.