labeledarray 0.4.0

# labeledarray

LabeledArray provides labeled n-dimensional arrays and helpers aimed at geospatial and scientific workflows built on ndarray.

Quick publish notes:
- Ensure Cargo.toml has valid metadata (description, authors, readme, license-file).
- Add a LICENSE file matching the license field.
- Run cargo package to verify the package contents before publishing:
  cargo package --allow-dirty

See the crate documentation at https://docs.rs/labeledarray (after first publish).

<!-- COVERAGE_BADGE_START -->
![coverage](coverage/badge.svg)
<!-- COVERAGE_BADGE_END -->
[![CI](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/ci.yml/badge.svg)](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/ci.yml)
[![Release and Publish](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/publish.yml/badge.svg)](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/publish.yml)
[![coverage](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/coverage.yml/badge.svg)](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/coverage.yml)

This library provides a structure for connecting human-readable dimension names (like "band", "time", "y", "x") to the underlying numerical data store powered by ndarray.

## Features

- **Labeled Dimensions**: Associate human-readable names with array dimensions
- **Coordinate Labels**: Attach coordinate labels to dimensions for easy data selection
- **Type-Safe**: Leverages Rust's type system for safe array operations
- **Performance**: Built on top of ndarray with optional parallel processing support via rayon

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
labeledarray = "0.1"
```

## Quick Start

```rust
use ndarray::ArrayD;
use labeledarray::LabeledArray;
use std::collections::HashMap;

// Create a simple 2D labeled array
let data = ArrayD::from_shape_vec(vec![3, 4], vec![
    1, 2, 3, 4,
    5, 6, 7, 8,
    9, 10, 11, 12
]).unwrap();
let dims = vec!["y".to_string(), "x".to_string()];
let array = LabeledArray::new(data, dims);

println!("Dimensions: {:?}", array.dims());
println!("Shape: {:?}", array.shape());
```

## Geospatial Example

```rust
use ndarray::ArrayD;
use labeledarray::LabeledArray;
use std::collections::HashMap;

// Create a 4D geospatial array: time × band × y × x
let data = ArrayD::from_shape_vec(vec![2, 3, 100, 100], vec![0.0; 60000]).unwrap();
let dims = vec![
    "time".to_string(),
    "band".to_string(),
    "y".to_string(),
    "x".to_string(),
];

let mut coords = HashMap::new();
coords.insert("time".to_string(), vec![
    "2024-01-01".to_string(), 
    "2024-01-02".to_string()
]);
coords.insert("band".to_string(), vec![
    "red".to_string(), 
    "green".to_string(), 
    "blue".to_string()
]);

let array = LabeledArray::with_coords(data, dims, coords);

// Query dimension indices
if let Some(idx) = array.dim_index("band") {
    println!("Band dimension is at index: {}", idx);
}

// Select by coordinate label
if let Some(idx) = array.select_by_label("band", "green") {
    println!("Green band is at index: {}", idx);
}
```

## API Overview

### Creating Arrays

- `LabeledArray::new(data, dims)` - Create array with dimension names
- `LabeledArray::with_coords(data, dims, coords)` - Create array with dimension names and coordinates

### Querying Array Information

- `dims()` - Get dimension names
- `shape()` - Get array shape
- `ndim()` - Get number of dimensions
- `data()` - Get reference to underlying ndarray
- `info()` - Get formatted string with array information

### Working with Coordinates

- `coords(dim)` - Get coordinates for a dimension
- `all_coords()` - Get all coordinates
- `set_coords(dim, coords)` - Set coordinates for a dimension
- `dim_index(dim)` - Get the index of a dimension by name
- `select_by_label(dim, label)` - Find the index of a coordinate label

## Examples

Run the included example:

```bash
cargo run --example basic_usage
```

## Future Development

This library is designed to be extended with additional geospatial functionality:

- Integration with geo-types for spatial operations
- STAC (SpatioTemporal Asset Catalog) support
- GDAL bindings for reading/writing geospatial formats
- Advanced indexing and selection operations
- Lazy evaluation and chunked processing

## License

[Add your license here]

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.