# 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).
[](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/ci.yml)
[](https://github.com/Wayfinder-Foundry/labeledarray/actions/workflows/publish.yml)
[](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.