feat: add bitround codec (#26)

* feat: add `bitround` codec

* feat: add `bitround` sample data

* fix: strip unnecessary attributes

Author: LDeakin

codecs/bitround/README.md

@@ -0,0 +1,96 @@
+# bitround codec
+
+Defines an `array -> array` codec to bit-round floating-point numbers and integers.
+
+## Codec name
+
+The value of the `name` member in the codec object MUST be `bitround` or a recognised alias.
+
+### Aliases
+#### `numcodecs.bitround` (Deprecated)
+
+Implementations may accept `numcodecs.bitround` as an alias for this codec.
+However, it is considered deprecated and `numcodecs.bitround` SHOULD NOT be used to store new data.
+
+## Configuration parameters
+
+### `keepbits` (Required)
+
+An integer specifying the number of bits to keep after rounding. Must be at least 1.
+
+For floating-point data types, this specifies the number of bits of the mantissa to retain.
+
+For integer data types, this specifies the number of bits to retain from the most significant set bit.
+
+## Example
+
+For example, the array metadata below specifies that the array contains bitrounded chunks:
+
+```json
+{
+    "codecs": [{
+        "name": "bitround",
+        "configuration": {
+            "keepbits": 10
+        }
+    }, { "name": "bytes", "configuration": { "endian": "little" } }]
+}
+```
+
+## Format and algorithm
+
+This is an `array -> array` codec that reduces the precision of numeric data to improve compressibility.
+
+### Floating-point data types
+
+For floating-point values, the codec rounds the mantissa to the specified number of bits (`keepbits`). This operation:
+- Preserves the sign and exponent
+- Rounds the mantissa, keeping only `keepbits` bits
+
+### Integer data types
+
+For integer values, the codec rounds from the most significant set bit. This operation:
+- Identifies the most significant bit that is set
+- Keeps `keepbits` bits starting from that position
+- Rounds the remaining lower-order bits to zero
+
+### Effect on compression
+
+By reducing precision, the `bitround` codec creates repeated patterns in the binary representation of the data, which may improve the compression ratio when used with subsequent bytes-to-bytes compression codecs (such as `gzip`, `zstd`, or `blosc`).
+
+## Supported data types
+
+### Floating-point types
+
+- `float16`, `float32`, `float64`
+- `bfloat16`
+- `complex_float16`, `complex_float32`, `complex_float64`
+- `complex_bfloat16`
+- `complex64`, `complex128`
+
+### Integer types
+
+- `int8`, `int16`, `int32`, `int64`
+- `uint8`, `uint16`, `uint32`, `uint64`
+- `numpy.timedelta64`, `numpy.datetime64` (encoded equivalently to `int64`)
+
+### Other types
+
+Implementations may support other data types that are interpretable as an integer or floating-point representation, or a composition of such primitives.
+
+## Compatibility
+
+This codec is compatible with `numcodecs.bitround` for floating-point data types.
+Integer data types are not supported by the `numcodecs.bitround` codec.
+
+## Sample Data
+
+Sample Zarr arrays encoded with the `bitround` codec can be found in the [sample_data](./sample_data) directory.
+
+## Change log
+
+No changes yet.
+
+## Current maintainers
+
+* Lachlan Deakin ([@LDeakin](https://github.com/LDeakin))

codecs/bitround/sample_data/README.md

@@ -0,0 +1,40 @@
+# `bitround` Codec Sample Data
+
+This directory contains sample Zarr arrays encoded with the `bitround` codec on `float32` and `uint8` data.
+
+Both arrays were encoded with the following `bitround` configuration, which retains 3 bits of precision:
+
+```json
+"name": "bitround",
+"configuration": {
+    "keepbits": 3
+}
+```
+
+### `bitround_float32.zarr`
+| Original           | Rounded           | Original (0b)                        | Rounded (0b)                         |
+|--------------------|-------------------|--------------------------------------|--------------------------------------|
+|           0.000000 |          0.000000 | `0_00000000_00000000000000000000000` | `0_00000000_00000000000000000000000` |
+|           0.100000 |          0.101562 | `0_01111011_10011001100110011001101` | `0_01111011_10100000000000000000000` |
+|           1.200000 |          1.250000 | `0_01111111_00110011001100110011010` | `0_01111111_01000000000000000000000` |
+|          12.300000 |         12.000000 | `0_10000010_10001001100110011001101` | `0_10000010_10000000000000000000000` |
+|         123.400002 |        120.000000 | `0_10000101_11101101100110011001101` | `0_10000101_11100000000000000000000` |
+|        1234.500000 |       1280.000000 | `0_10001001_00110100101000000000000` | `0_10001001_01000000000000000000000` |
+|                NaN |               NaN | `0_11111111_10000000000000000000000` | `0_11111111_10000000000000000000000` |
+|                inf |               inf | `0_11111111_00000000000000000000000` | `0_11111111_00000000000000000000000` |
+|               -inf |              -inf | `1_11111111_00000000000000000000000` | `1_11111111_00000000000000000000000` |
+
+### `bitround_uint8.zarr`
+
+| Original | Rounded | Original (0b) | Rounded (0b) |
+|----------|---------|---------------|--------------|
+|        0 |       0 |    `00000000` |   `00000000` |
+|        1 |       1 |    `00000001` |   `00000001` |
+|       10 |      10 |    `00001010` |   `00001010` |
+|       11 |      12 |    `00001011` |   `00001100` |
+|      100 |      96 |    `01100100` |   `01100000` |
+|      123 |     128 |    `01111011` |   `10000000` |
+|      200 |     192 |    `11001000` |   `11000000` |
+|      208 |     192 |    `11010000` |   `11000000` |
+|      209 |     224 |    `11010001` |   `11100000` |
+|      255 |     224 |    `11111111` |   `11100000` |

codecs/bitround/sample_data/bitround_float32.zarr/c/0

@@ -0,0 +1,37 @@
+{
+  "zarr_format": 3,
+  "node_type": "array",
+  "shape": [
+    9
+  ],
+  "data_type": "float32",
+  "chunk_grid": {
+    "name": "regular",
+    "configuration": {
+      "chunk_shape": [
+        9
+      ]
+    }
+  },
+  "chunk_key_encoding": {
+    "name": "default",
+    "configuration": {
+      "separator": "/"
+    }
+  },
+  "fill_value": 0.0,
+  "codecs": [
+    {
+      "name": "bitround",
+      "configuration": {
+        "keepbits": 3
+      }
+    },
+    {
+      "name": "bytes",
+      "configuration": {
+        "endian": "little"
+      }
+    }
+  ]
+}

codecs/bitround/sample_data/bitround_float32.zarr/zarr.json

@@ -0,0 +1,37 @@
+{
+  "zarr_format": 3,
+  "node_type": "array",
+  "shape": [
+    10
+  ],
+  "data_type": "uint8",
+  "chunk_grid": {
+    "name": "regular",
+    "configuration": {
+      "chunk_shape": [
+        10
+      ]
+    }
+  },
+  "chunk_key_encoding": {
+    "name": "default",
+    "configuration": {
+      "separator": "/"
+    }
+  },
+  "fill_value": 0,
+  "codecs": [
+    {
+      "name": "bitround",
+      "configuration": {
+        "keepbits": 3
+      }
+    },
+    {
+      "name": "bytes",
+      "configuration": {
+        "endian": "little"
+      }
+    }
+  ]
+}

codecs/bitround/sample_data/bitround_uint8.zarr/c/0

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "const": "bitround"
+    },
+    "configuration": {
+      "type": "object",
+      "properties": {
+        "keepbits": {
+          "type": "integer",
+          "minimum": 0
+        }
+      },
+      "required": ["keepbits"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["name", "configuration"],
+  "additionalProperties": false
+}