# shrinkage::DisjointGroups

Shrinkage for Rust · 0.3.0

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

```rust
pub struct DisjointGroups
```

Validated disjoint groups of optimization-scale coefficient indices. 

Groups and their members retain the supplied order. Indices address a vector of `ncoefficients` entries, excluding intercepts. For a flattened coefficient matrix, use [`crate::CoefficientLayout::index`](<62149afd3598115cd84b1d082cb6c3684abff0b85239710acbface17a12565fe#method-index-5222adba01ad98d120d848fd5d72519414864fba2820d2489dcc7ecc7ef2803a>) to respect its response-major layout. Each coefficient belongs to at most one group. 

Supply one finite, nonnegative weight per group. Weights are multipliers of group penalty values, stored without adjustment for group size or count. A zero weight still counts as coverage and must obey all membership rules. The coverage policy explicitly requires full coverage or leaves uncovered coefficients unpenalized. All definitions are checked at construction and exposed through immutable slices. 

```rust
use shrinkage::{DisjointGroups, UncoveredPolicy};

let groups = DisjointGroups::new(
    5,
    vec![vec![3, 1], vec![0]],
    vec![0.5, 2.0],
    UncoveredPolicy::Unpenalized,
)?;
assert_eq!(groups.groups(), [vec![3, 1], vec![0]]);
assert_eq!(groups.weights(), [0.5, 2.0]);
assert_eq!(groups.uncovered(), [2, 4]);
```

<a id="impl-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41"></a>

## Inherent implementation

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

```rust
impl DisjointGroups
```

<a id="method-groups-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41"></a>

### `groups`

```rust
pub fn groups(&self) -> &[Vec<usize>]
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

Disjoint index vectors in their supplied group and member order. 

<a id="method-ncoefficients-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41"></a>

### `ncoefficients`

```rust
pub fn ncoefficients(&self) -> usize
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

Coefficient vector length, excluding intercepts. 

<a id="method-new-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41"></a>

### `new`

```rust
pub fn new(
    ncoefficients: usize,
    groups: Vec<Vec<usize>>,
    weights: Vec<f64>,
    uncovered_policy: UncoveredPolicy
) -> Result<Self, FitError>
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

Validate and own weighted groups over a fixed coefficient vector. 

Individual groups must be nonempty. An empty collection is valid for zero coefficients under either policy, or for any coefficient count under [`UncoveredPolicy::Unpenalized`](<e0d60cff0503b5585045fbf4ef267ac7ed3714eacbabd19c2c1e90541848f6b7#variant-Unpenalized>). 

<a id="method-new-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41-documentation-errors"></a>

#### Errors

Reject a weight count different from the group count, nonfinite or negative weights, empty groups, repeated indices within a group, overlapping groups (including duplicate groups), or indices outside `0..ncoefficients`. [`UncoveredPolicy::Reject`](<e0d60cff0503b5585045fbf4ef267ac7ed3714eacbabd19c2c1e90541848f6b7#variant-Reject>) also rejects any coefficient omitted from the groups. Errors identify group and coefficient indices using zero-based numbering when applicable. 

<a id="method-uncovered-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41"></a>

### `uncovered`

```rust
pub fn uncovered(&self) -> &[usize]
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

Uncovered coefficient indices in increasing order. 

Always empty under [`UncoveredPolicy::Reject`](<e0d60cff0503b5585045fbf4ef267ac7ed3714eacbabd19c2c1e90541848f6b7#variant-Reject>). Under [`UncoveredPolicy::Unpenalized`](<e0d60cff0503b5585045fbf4ef267ac7ed3714eacbabd19c2c1e90541848f6b7#variant-Unpenalized>), these coefficients remain unpenalized. 

<a id="method-uncovered_policy-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41"></a>

### `uncovered_policy`

```rust
pub fn uncovered_policy(&self) -> UncoveredPolicy
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

Policy governing coefficients outside every group. 

<a id="method-weights-aa7b57fb9e134b20df183fb3b7d8d2b9045c5cce2465a94a89b347df2f51da41"></a>

### `weights`

```rust
pub fn weights(&self) -> &[f64]
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

One finite, nonnegative weight per group, in group order. 

<a id="impl-b859bbd4aaf777e2f658577d1628fc3135e4b1a126cc5c80ef085e672e27851a"></a>

## Implementation of Clone

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

```rust
impl Clone for DisjointGroups
```

<a id="method-clone-b859bbd4aaf777e2f658577d1628fc3135e4b1a126cc5c80ef085e672e27851a"></a>

### `clone`

```rust
fn clone(&self) -> Self
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

<a id="impl-489ca783185da0b7e1111351651607fe4f83ec435ebe9abe7087a6ff5192e169"></a>

## Implementation of Debug

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

```rust
impl Debug for DisjointGroups
```

<a id="method-fmt-489ca783185da0b7e1111351651607fe4f83ec435ebe9abe7087a6ff5192e169"></a>

### `fmt`

```rust
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
```

[Source](<https://github.com/jolars/shrinkage/blob/eeafe449edce19d3c552a03060f681ae3891af74/src/penalty/groups.rs>)

<a id="impl-c4c22fe742439ec301ef2b7389a77f01f8e549f912ab8b5e754d3e66df101363"></a>

## Implementation of Freeze

```rust
impl Freeze for DisjointGroups
```

<a id="impl-2f8daabd6db7bb34eeac80e1971bb4c73692fb0d330baa8d298294ee867c6fcb"></a>

## Implementation of RefUnwindSafe

```rust
impl RefUnwindSafe for DisjointGroups
```

<a id="impl-7852134c5e0cb519c9c44ab7c50779820c028604e2914ce6e7c6d429c471ef40"></a>

## Implementation of Send

```rust
impl Send for DisjointGroups
```

<a id="impl-82a42cfcd823c352e18a43ac2d6229f7a9a93c132225c5b2b55f01f7f2a4304f"></a>

## Implementation of Sync

```rust
impl Sync for DisjointGroups
```

<a id="impl-1bd622ab38ece1cbd8ec2ca682475bdadf206939acc3dedb489c540c2289e470"></a>

## Implementation of Unpin

```rust
impl Unpin for DisjointGroups
```

<a id="impl-f433a721ea6f2910d1de219ed23020fe70540eeab77c04e8076b8833847cc016"></a>

## Implementation of UnsafeUnpin

```rust
impl UnsafeUnpin for DisjointGroups
```

<a id="impl-5e797c8679ef619461bbe1ae9ad41fa23d5a593d2051e9004677379ea226ccbd"></a>

## Implementation of UnwindSafe

```rust
impl UnwindSafe for DisjointGroups
```

<a id="impl-1e5682dc18e03c648aa9b125290c107c1e8d96ce8a179a8532e4057da4daf0cd"></a>

## Implementation of Any

```rust
impl<T> Any for T where T: 'static + ?Sized
```

<a id="impl-6c0b25c2c92cdb117802d9c0a4c70afc9a8bfb0da875bc6e66191e2349fcdf3f"></a>

## Implementation of Borrow

```rust
impl<T> Borrow<T> for T where T: ?Sized
```

<a id="impl-796e80d926348273a22b04d8e84f510693b11c06ec57c3c3e2e8c1524094a85c"></a>

## Implementation of BorrowMut

```rust
impl<T> BorrowMut<T> for T where T: ?Sized
```

<a id="impl-8360e4092e7ec4a05a26dd304cd739398f0cacc50c8d08dd5be0223d1a08d02e"></a>

## Implementation of ByRef

```rust
impl<T> ByRef<T> for T
```

<a id="impl-dbb1293b7b5dd80c4d9a98cfdd6843dc7470224c0b1387731cd418da07046d7b"></a>

## Implementation of CastableFrom

```rust
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT where ST: ?Sized, DT: ?Sized
```

<a id="impl-97b65e7dfc44b5ecaa495a3a19fe737914a1e9f8532200cf8f46191314e7d777"></a>

## Implementation of CastableFrom

```rust
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT where ST: ?Sized, DT: ?Sized
```

<a id="impl-86d7da2bfd1140cc1675dfe6a975e6a2762338ab32731152da0723858ef3aa81"></a>

## Implementation of CloneToUninit

```rust
impl<T> CloneToUninit for T where T: Clone
```

<a id="impl-c22bdd3b1b677b66eb32d1c182cc1410c7f0c46491dd74e6a659647c238d19ec"></a>

## Implementation of From

```rust
impl<T> From<T> for T
```

<a id="impl-5adf6ca1830f30fbbac655ab8ff394d254954df7ededc7cc833c72fdc87d6f00"></a>

## Implementation of Imply

```rust
impl<T, U> Imply<T> for U where T: ?Sized, U: ?Sized
```

<a id="impl-85eec431edd188129f88290bbcb748e4d2fdc97f7efef3c162b8c252286ffec0"></a>

## Implementation of Into

```rust
impl<T, U> Into<U> for T where U: From<T>
```

<a id="impl-c40268dd59dd3329202d3c0544c62372e98ff3baa8ec442ec00752e024ec1d06"></a>

## Implementation of IntoEither

```rust
impl<T> IntoEither for T
```

<a id="impl-5655b1ef858b34a584cb80104f040c8a4063ced0d281311a0833ed12aefde86e"></a>

## Implementation of Pointable

```rust
impl<T> Pointable for T
```

<a id="impl-8cc2aa01198fc9fa44f08b889f62988d70d2a7f4f0f11f4666d4c08bdaddb22a"></a>

## Implementation of Read

```rust
impl<T> Read<Exclusive, BecauseExclusive> for T where T: ?Sized
```

<a id="impl-5ea09131039c62dd92b119d480a35c7e2b33d2b81dccf0b849f6b1f19f4bda24"></a>

## Implementation of Same

```rust
impl<T> Same for T
```

<a id="impl-7ee6ff38d6674f5edfe4734359062c2a67a572cff5899a89704764822b931c7f"></a>

## Implementation of SupersetOf

```rust
impl<SS, SP> SupersetOf<SS> for SP where SS: SubsetOf<SP>
```

<a id="impl-a8ef6e94191301c3685488478f4905086c47137bac2d606ea4d09631d5472b06"></a>

## Implementation of ToOwned

```rust
impl<T> ToOwned for T where T: Clone
```

<a id="impl-83960135d00d98080c95a08867729696e36811280c2dd9cf34c1b4fe21c81e18"></a>

## Implementation of TryFrom

```rust
impl<T, U> TryFrom<U> for T where U: Into<T>
```

<a id="impl-1cc495bcaa5112ffb304e7f0de674feca391fd97f47bec86033a9225b72ac05c"></a>

## Implementation of TryInto

```rust
impl<T, U> TryInto<U> for T where U: TryFrom<T>
```