# Kislovodsk Sunspot Group Data — `kYYYY.dat`

Annual plain-text files contain observations of sunspot groups. `YYYY` is the four-digit year. Files are read with `open_kyyyy_dat` from `io.py`.

Each data line describes one group at one observation time. Multiple groups observed at the same time occupy separate lines. The file has no column header. Records use fixed-width fields; spaces within empty fields must be preserved.

## Record Layout

Column positions are one-based and inclusive. Python slices are zero-based, with an exclusive upper bound.

| Columns | Python slice | Width | Field | Description |
| --- | --- | --- | --- | --- |
| 1–12 | `[0:12]` | 12 | `date_time` | Observation date and fractional UT day, `YYYYMMDD.ff` |
| 13–19 | `[12:19]` | 7 | `group_number` | Kislovodsk sunspot group number |
| 20–28 | `[19:28]` | 9 | `lat` | Heliographic latitude, degrees; positive north, negative south |
| 29–36 | `[28:36]` | 8 | `lon` | Carrington longitude, degrees |
| 37–42 | `[36:42]` | 6 | `r/R` | Projected distance from disk center divided by the apparent solar radius |
| 43–49 | `[42:49]` | 7 | `area_uncorrected` | Projected total group area, in millionths of the apparent solar disk |
| 50–56 | `[49:56]` | 7 | `area` | Total group area corrected for foreshortening, in millionths of a solar hemisphere (MSH) |
| 57–63 | `[56:63]` | 7 | `area_max` | Corrected area of the largest individual spot in the group at this observation, in MSH |
| 64–68 | `[63:68]` | 5 | `n_spots` | Number of spots in the group |
| 69 onward | `[68:]` | Variable | Annotation | Optional source label or supplementary information |

Numeric fields use a decimal point. Group numbers and spot counts are integers. Trailing spaces and empty fields at the end of a record can be omitted.

## Date and Time

The date field consists of a calendar date followed by the fraction of a 24-hour day:

```text
YYYYMMDD.ff
```

The time in UTC is midnight plus `0.ff × 24` hours. For example, `.25` corresponds to 06:00 UTC and `.30` to 07:12 UTC. Two decimal places give a time increment of 0.01 day, or 14 minutes 24 seconds.

The fractional part must retain its decimal place value: `.30` and `.3` both mean 0.3 day. The digits after the decimal point are not hours or minutes.

## Coordinates and Areas

`r/R` is dimensionless: zero denotes disk center and one denotes the limb.

The projected and corrected group areas use different normalization surfaces: the apparent disk and the solar hemisphere, respectively. The geometric relationship is

```text
area ≈ area_uncorrected / (2 × sqrt(1 − (r/R)²))
```

This relationship describes the normalization and foreshortening correction; rounded tabulated values need not reproduce it exactly, especially near the limb.

`area_max` describes the largest spot in the current observation, not the maximum group area over its lifetime.

## Missing Fields and Historical Records

Blank fields denote missing entries. A line containing only `date_time` records an observation with no listed sunspot groups; it is not a group record. Empty lines contain no data.

Before 2009, group coordinates were recorded for central-meridian passage rather than repeated in each daily record. Other observations of the same group therefore have blank `lat` and `lon` fields while retaining `r/R`, areas, and spot count. Later records provide coordinates for individual observations.

Group numbers identify groups within the Kislovodsk catalogue. Groups continuing across New Year can retain their existing numbers alongside newly numbered groups.

## Annotations

Text after column 68 is separate from the nine numeric fields:

- `SDO` marks observations based on Solar Dynamics Observatory data.
- Parenthesized entries such as `(I-14.3)` give a central-meridian passage date: Roman-numeral month followed by the day and its fractional part.

## Reading

Use `open_kyyyy_dat(path)` from `io.py`. The returned table uses the nine field names listed above and UTC-aware observation times. The optional `fill_coordinates=True` fills missing coordinates from the nearest coordinate-bearing record of the same group.

The reader represents blank numeric fields as `NaN`, then replaces missing area and spot-count values with zero. These zeros are reader output; the original file stores blank fields.