`lz76()`¶

Run the complete analysis of one sequence. The dictionary contains the LZ76 count, factor boundaries, entropy density h, effective measure complexity E, its range profile and diagnostic fields. Use it when you need several of these results together: the original factorization is shared between the calculations.

lz76(seq, partitions=1, alphabet=None, log_base=None,
     max_block_size=-1, jobs=0) -> dict

Parameters¶

Parameter	Default	Behavior
`seq`	required	Supported sequence input, converted to bytes.
`partitions`	`1`	Accepted; has no effect.
`alphabet`	`None`	Alphabet parameter for `epsilon`. Omitted: observed byte alphabet, with a minimum of two. Does not select the logarithm base or change h and E.
`log_base`	`None`	Base for h, E and normalization diagnostics. Omitted: observed byte alphabet, with a minimum of two. Values zero and one are treated as two.
`max_block_size`	`-1`	Maximum range for E in bytes. Positive values set it explicitly; zero or a negative value selects it automatically.
`jobs`	`0`	Accepted; has no effect. Native workers use Rayon configuration.

For argument types, integer ranges and exceptions, see the shared parameter reference.

Calculate the main quantities¶

import lzcomplexity as lz

sequence = b"00010111" * 256
result = lz.lz76(sequence, log_base=2, max_block_size=8)

assert result["complexity"] == 4
assert result["h"] == 0.021484375
assert result["emc"]["value"] == 3.2105712890625

Output values are built-in Python dictionaries, lists, integers and floats. The input object is not modified.

Complete return schema¶

Key	Type	Meaning
`complexity`	`int`	Completed LZ76 factor count.
`factors`	`list[int]`	Byte boundaries. The final boundary may exceed the input length.
`h`	`float`	Entropy density in the selected logarithm-base units per input byte.
`emc`	`dict`	E, profile increments, selected range and first-range contrast; details below.
`epsilon`	`float`	Finite-size diagnostic using input length, alphabet parameter and logarithm base.
`factors_stddev`	`float`	Factor-dispersion diagnostic calculated from boundary intervals.
`normal_error`	`float`	Diagnostic combining h, factor dispersion and input length.
`poison_error`	`float`	`h / N` for byte length `N > 1`, otherwise zero. The API spells this key `poison_error`.
`extras`	`dict`	Five ratios comparing factor counts of the input and its halves; details below.

complexity and factors use the conventions of factorization(). A copied terminal tail can produce an overshooting boundary while being excluded from the count. Use the actual input byte length rather than its last boundary as N.

Effective measure complexity result¶

result["emc"] contains:

Key	Type	Meaning
`value`	`float`	E: final level of the fitted nonnegative, nondecreasing range profile.
`summands`	`list[float]`	Nonnegative fitted increments in range order, summing to E.
`max_block_size`	`int`	Actual largest range included, explicit or selected automatically.
`multi_information`	`float`	First-range contrast before fitting; it can be negative.

import math
import lzcomplexity as lz

result = lz.lz76(b"00010111" * 256, log_base=2, max_block_size=8)
profile = result["emc"]

assert profile["max_block_size"] == 8
assert len(profile["summands"]) == 8
assert math.isclose(sum(profile["summands"]), profile["value"], abs_tol=1e-12)

See emc() for range selection, reconstructing the profile and comparing samples consistently.

Additional count-based ratios¶

The input is split at N // 2. For odd byte lengths, the second half has one extra byte. Let F and L be the first- and second-half factor counts, C the whole-input count, and Q = F + L - C.

`extras` key	Type	Returned ratio
`rajski_distance`	`float`	`2 - (F + L) / C`
`redundancy`	`float`	`Q / (F + L)`
`fh_uncertainty`	`float`	`Q / F`
`lh_uncertainty`	`float`	`Q / L`
`pearson_coefficient`	`float`	`Q / sqrt(F * L)`

These fields describe the halves of this one sequence. Use nid() to compare two separate sequences. The count-based pearson_coefficient is distinct from a sample Pearson correlation between numeric observations.

Interpret the diagnostic fields¶

epsilon, factors_stddev, normal_error and poison_error summarize the finite input and its factorization. factors_stddev uses the library's interval-based normalization, including any overshooting final boundary; it is not the usual sample standard deviation of displayed phrase lengths.

The complete definitions and worked examples are on reading the numbers. These are descriptive formulas. Estimate experimental uncertainty from independent observations or suitable resampling when confidence intervals are required.

Empty and constant inputs¶

The dictionary always has the same structure. Empty and constant sequences return complexity = 1; empty input has factors = [0, 1, 0]. h is zero for byte lengths zero and one, while longer constant inputs have the finite-size value log_b(N) / N. E is zero for constant inputs.

An explicit positive max_block_size=M produces M zero increments for an empty or constant input. Diagnostic and extras fields need not all be zero: they follow their formulas and the special factor-count convention.

Save a result¶

import json
import lzcomplexity as lz

sequence = b"00010111" * 256
settings = {"log_base": 2, "max_block_size": 8}
record = {
    "input_length_bytes": len(sequence),
    "settings": settings,
    "result": lz.lz76(sequence, **settings),
}
serialized = json.dumps(record)
assert json.loads(serialized)["result"]["complexity"] == 4

Retain input encoding and preprocessing with the settings. The reproducibility guide shows an analysis record with an input fingerprint and package version.

lz76()¶