> The significance score used for ranking is more subtle than actual / expected because that has a big bias towards very rare terms. Rare terms can easily experience relatively big jumps in stats (e.g. expected =1 vs actual 2) and more common words cannot experience those same levels of growth as easily. It's like how fleas can jump much higher than elephants (relatively speaking). So in the significance score I use the magnitude of the jump is tempered by a sense of scale.

> I'd like to see the actual significance-score used for ranking retained in here somewhere otherwise the "expected vs actual" score you propose does not actually match the sort order/selection criteria used behind the scenes. 

Fair enough - I took a naive approach with very little understanding :) I'm happy with however you calculate that number. I'd just reduce the name to `score` or `weight` rather than the longer `significance_score`.

> "Expected" ("bg_count?") is a derived number and a bit of a guess, whereas supplying the background frequency feels like you are giving clients more reliable stats from which they can draw their own expectations.

OK. The `superset_size` is really just the number of docs in the index (or later, if we allow filtering on the superset, then the `doc_count` of that collection).  This number is the same for all buckets and can be derived easily using (eg) a `global` agg should the user want it, so I think it can be safely left out.

To provide  a number representing the count of this-term-in-the-superset, derived from docFreq, perhaps `bg_freq` would be ok? Although, I'd kinda expect a frequency to be expressed as a percentage, but that may just be me. Perhaps people with a Lucene background expect a frequency to be an absolute number instead.

How about:

     "aggregations" : {
         "superset_size": {
            "doc_count": 5064554   # 1
         },
         "significantCrimeTypes" : {
             "doc_count": 47347,        # 2
             "buckets" : [
                 {
                     "key": "Bicycle theft",
                     "doc_count": 3640,       # 3
                     "score": 0.371235374214817, # 4
                     "bg_freq": 66799 # 5
                     "bg_expected": 473  # 6
                 }

Where:

1. The optional superset size derived from a `global` agg.
2. The number of docs in the `significant_terms` subset
3. The number of docs in the subset with term `Bicycle theft`
4. The significance score calculated however you do it
5. The doc frequency of the term `Bicycle theft` in the superset
6. Optionally, the derived number of occurrences that we'd expect based on the bg frequency.