dslighting 1.3.9__py3-none-any.whl → 1.7.1__py3-none-any.whl

dslighting/registry/histopathologic-cancer-detection/prepare_val.py

@@ -0,0 +1,131 @@
+import shutil
+from pathlib import Path
+
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from tqdm import tqdm
+
+
+def _create_split(
+    df_to_split: pd.DataFrame,
+    image_source_dir: Path,
+    test_split_size: float,
+    public_dest: Path,
+    private_dest: Path,
+    random_state: int,
+) -> pd.DataFrame:
+    """
+    Splits a dataframe of labels, copies corresponding images, and saves the results.
+
+    Args:
+        df_to_split: DataFrame containing image IDs and labels to be split.
+        image_source_dir: Path to the directory containing the source images.
+        test_split_size: The proportion of the dataset to allocate to the test split.
+        public_dest: The destination directory for public-facing files (train set, test images, sample submission).
+        private_dest: The destination directory for private files (test set answers).
+        random_state: The seed used by the random number generator for the split.
+
+    Returns:
+        The training portion of the split as a pandas DataFrame.
+    """
+    # Create destination directories
+    public_dest.mkdir(exist_ok=True, parents=True)
+    private_dest.mkdir(exist_ok=True, parents=True)
+    (public_dest / "train").mkdir(exist_ok=True)
+    (public_dest / "test").mkdir(exist_ok=True)
+
+    # Perform the split
+    train_ids, test_ids = train_test_split(
+        df_to_split["id"], test_size=test_split_size, random_state=random_state
+    )
+    train_df = df_to_split[df_to_split["id"].isin(train_ids)]
+    test_df = df_to_split[df_to_split["id"].isin(test_ids)]
+
+    assert set(train_df["id"]).isdisjoint(
+        set(test_df["id"])
+    ), "Train should not contain id's of test images"
+    assert len(train_ids) + len(test_ids) == len(
+        df_to_split
+    ), "The combined length of train_ids and test_ids should equal the length of the source df"
+
+    # Copy over image files
+    for file_id in tqdm(train_ids, desc=f"Copying train images to {public_dest}"):
+        shutil.copyfile(
+            src=image_source_dir / f"{file_id}.tif",
+            dst=public_dest / "train" / f"{file_id}.tif",
+        )
+    for file_id in tqdm(test_ids, desc=f"Copying test images to {public_dest}"):
+        shutil.copyfile(
+            src=image_source_dir / f"{file_id}.tif",
+            dst=public_dest / "test" / f"{file_id}.tif",
+        )
+
+    # Create and save label/submission files
+    sample_submission = test_df.copy()
+    sample_submission["label"] = 0
+
+    train_df.to_csv(public_dest / "train_labels.csv", index=False)
+    test_df.to_csv(private_dest / "answers.csv", index=False)
+    sample_submission.to_csv(public_dest / "sample_submission.csv", index=False)
+
+    # Check integrity of files copied
+    assert len(list(public_dest.glob("train/*.tif"))) == len(
+        train_ids
+    ), "Number of train images should be equal to the number of unique id's in the train set"
+    assert len(list(public_dest.glob("test/*.tif"))) == len(
+        test_ids
+    ), "Number of test images should be equal to the number of unique id's in the test set"
+
+    return train_df
+
+
+def prepare(raw: Path, public: Path, private: Path):
+    """
+    Prepares the data for the competition by performing two splits.
+    1. A main split of the raw data into a primary train/test set for the competition.
+       Outputs are saved to `public/` and `private/`.
+    2. A secondary split of the primary train set into a smaller train/validation set for user convenience.
+       Outputs are saved to `public_val/` and `private_val/`, mirroring the main structure.
+    """
+    # Common setup
+    all_train_labels = pd.read_csv(raw / "train_labels.csv")
+    image_source_dir = raw / "train"
+    RANDOM_STATE = 0
+
+    # --- 1. Main Split: Create the primary train/test sets ---
+    # This logic is identical to the original script to ensure outputs do not change.
+    num_test_from_pool = len(list((raw / "test").glob("*.tif")))
+    test_ratio_main = num_test_from_pool / (len(all_train_labels) + num_test_from_pool)
+
+    # The returned `primary_train_df` is the larger portion of the first split.
+    primary_train_df = _create_split(
+        df_to_split=all_train_labels,
+        image_source_dir=image_source_dir,
+        test_split_size=test_ratio_main,
+        public_dest=public,
+        private_dest=private,
+        random_state=RANDOM_STATE,
+    )
+
+    # --- 2. Validation Split: Create a secondary train/validation set ---
+    # Define new output paths for the validation split
+    public_val = public.parent / "public_val"
+    private_val = private.parent / "private_val"
+
+    # To get the same number of test samples as the main split, we must adjust the test_size
+    # for this second split, which operates on a smaller dataset (the primary_train_df).
+    if (1 - test_ratio_main) <= 0:
+        # Avoid division by zero in the unlikely case the main split uses all data for test
+        test_ratio_val = 0
+    else:
+        test_ratio_val = test_ratio_main / (1 - test_ratio_main)
+
+    # Perform the second split on the primary training data
+    _create_split(
+        df_to_split=primary_train_df,
+        image_source_dir=image_source_dir,
+        test_split_size=test_ratio_val,
+        public_dest=public_val,
+        private_dest=private_val,
+        random_state=RANDOM_STATE,
+    )

dslighting/registry/hms-harmful-brain-activity-classification/checksums.yaml

@@ -0,0 +1,8 @@
+private:
+  gold_submission.csv: ba90c5dda42c504e3638af6ee7dc46fb
+  test.csv: 205ee658cf7e8cfd317e7bee6045dffd
+public:
+  sample_submission.csv: 5e8cb4e5956283462cbc704e1f09af4d
+  test.csv: dfe1f087a65ffa7c7341cdcdfc143554
+  train.csv: c82b8b6f36e0a20932c5566957f6eb63
+zip: bbf763e3e95da2e325ab82624462d342

dslighting/registry/hms-harmful-brain-activity-classification/config.yaml

@@ -0,0 +1,27 @@
+id: hms-harmful-brain-activity-classification
+name: HMS - Harmful Brain Activity Classification
+competition_type: code
+awards_medals: true
+prizes: 
+  - position: 1
+    value: 20000
+  - position: 2
+    value: 12000
+  - position: 3
+    value: 7000
+  - position: 4
+    value: 6000
+  - position: 5
+    value: 5000
+description: mlebench/competitions/hms-harmful-brain-activity-classification/description.md
+
+dataset:
+  answers: hms-harmful-brain-activity-classification/prepared/private/test.csv
+  gold_submission: hms-harmful-brain-activity-classification/prepared/private/gold_submission.csv
+  sample_submission: hms-harmful-brain-activity-classification/prepared/public/sample_submission.csv
+
+grader:
+  name: KL-divergence
+  grade_fn: mlebench.competitions.hms-harmful-brain-activity-classification.grade:grade
+
+preparer: mlebench.competitions.hms-harmful-brain-activity-classification.prepare:prepare

dslighting/registry/hms-harmful-brain-activity-classification/constants.py

@@ -0,0 +1,9 @@
+ID_COL = "eeg_id"
+TARGET_COLS = [
+    "seizure_vote",
+    "lpd_vote",
+    "gpd_vote",
+    "lrda_vote",
+    "grda_vote",
+    "other_vote",
+]

dslighting/registry/hms-harmful-brain-activity-classification/description.md

@@ -0,0 +1,166 @@
+# Overview
+
+## Overview
+
+The goal of this competition is to detect and classify seizures and other types of harmful brain activity. You will develop a model trained on electroencephalography (EEG) signals recorded from critically ill hospital patients.
+
+Your work may help rapidly improve electroencephalography pattern classification accuracy, unlocking transformative benefits for neurocritical care, epilepsy, and drug development. Advancement in this area may allow doctors and brain researchers to detect seizures or other brain damage to provide faster and more accurate treatments.
+
+### Description
+
+From stethoscopes to tongue depressors, doctors rely on many tools to treat their patients. Physicians use electroencephalography with critically ill patients to detect seizures and other types of brain activity that can cause brain damage. You can learn about how doctors interpret these EEG signals in these videos:\
+EEG Talk - ACNS Critical Care EEG Terminology 2021 [(Part 1)](https://www.youtube.com/watch?v=S9NLrhj0x-M&t) [(Part 2)](https://www.youtube.com/watch?v=4D9R2WIKr-A) [(Part 3)](https://www.youtube.com/watch?v=-R5yUX7p_j4) [(Part 4)](https://www.youtube.com/watch?v=OknS2ObD9-g&t) [(Part 5)](https://www.youtube.com/watch?v=2c7ABQRkn3s)
+
+Currently, EEG monitoring relies solely on manual analysis by specialized neurologists. While invaluable, this labor-intensive process is a major bottleneck. Not only can it be time-consuming, but manual review of EEG recordings is also expensive, prone to fatigue-related errors, and suffers from reliability issues between different reviewers, even when those reviewers are experts.
+
+Competition host Sunstella Foundation was created in 2021 during the COVID pandemic to help minority graduate students in technology overcome challenges and celebrate their achievements. These students are vital to America's technology leadership and diversity. Through workshops, forums, and competitions, the Sunstella Foundation provides mentorship and career advice to support their success.
+
+Sunstella Foundation is joined by Persyst, Jazz Pharmaceuticals, and the Clinical Data Animation Center (CDAC), whose research aims to help people preserve and enhance brain health.
+
+Your work in automating EEG analysis will help doctors and brain researchers detect seizures and other types of brain activity that can cause brain damage, so that they can give treatments more quickly and accurately. The algorithms developed in this contest may also help researchers who are working to develop drugs to treat and prevent seizures.
+
+There are six patterns of interest for this competition: seizure (SZ), generalized periodic discharges (GPD), lateralized periodic discharges (LPD), lateralized rhythmic delta activity (LRDA), generalized rhythmic delta activity (GRDA), or "other". Detailed explanations of these patterns are [available here.](https://www.acns.org/UserFiles/file/ACNSStandardizedCriticalCareEEGTerminology_rev2021.pdf)
+
+The EEG segments used in this competition have been annotated, or classified, by a group of experts. In some cases experts completely agree about the correct label. On other cases the experts disagree. We call segments where there are high levels of agreement "idealized" patterns. Cases where ~1/2 of experts give a label as "other" and ~1/2 give one of the remaining five labels, we call "proto patterns". Cases where experts are approximately split between 2 of the 5 named patterns, we call "edge cases".
+
+Examples of EEG Patterns with Different Levels of Expert Agreement:\
+![](https://storage.googleapis.com/kaggle-media/competitions/Harvard%20Medical%20School/eFig2.png)\
+*Please refer to [Data tab](https://www.kaggle.com/competitions/hms-harmful-brain-activity-classification/data) for full screen PDF page of each subfigure.*
+
+This figure shows selected examples of EEG patterns with different level of agreement. Rows are structured with the 1st row seizure, 2nd row LPDs, 3rd row GPDs, 4th row LRDA, and 5th row GRDA. Column-wise, examples of idealized forms of patterns are in the 1st column (A). These are patterns with uniform expert agreement. The 2nd column (B) are proto or partially formed patterns. About half of raters labeled these as one IIIC pattern and the other half labeled "Other". The 3rd and 4th columns (C, D) are edge cases (about half of raters labeled these one IIIC pattern and half labeled them as another IIIC pattern).
+
+For B-1 there is rhythmic delta activity with some admixed sharp discharges within the 10 second raw EEG, and the spectrogram shows that this segment may belong to the tail end of a seizure, thus disagreement between SZ and "Other" makes sense. B-2 shows frontal lateralized sharp transients at ~1Hz, but they have a reversed polarity, suggesting they may be coming from a non-cerebral source, thus the split between LPD and "Other" (artifact) makes sense. B-3 has diffused semi-rhythmic delta background with poorly formed low amplitude generalized periodic discharges with s shifting morphology making it a proto-GPD type pattern. B-4 shows semi-rhythmic delta activity with unstable morphology over the right hemisphere, a proto-LRDA pattern. B-5 shows a few waves of rhythmic delta activity with an unstable morphology and is poorly sustained, a proto-GRDA. C-1 shows 2Hz LPDs showing an evolution with increasing amplitude evolving underlying rhythmic activity, a pattern between LPDs and the beginning of a seizure, an edge-case. D-1 shows abundant GPDs on top of a suppressed background with frequency of 1-2Hz. The average over the 10-seconds is close to 1.5Hz, suggesting a seizure, another edge case. C-2 is split between LPDs and GPDs. The amplitude of the periodic discharges is higher over the right, but a reflection is also seen on the left. D-2 is tied between LPDs and LRDA. It shares some features of both; in the temporal derivations it looks more rhythmic whereas in the parasagittal derivations it looks periodic. C-3 is split between GPDs and LRDA. The ascending limb of the delta waves have a sharp morphology, and these periodic discharges are seen on both sides. The rhythmic delta appears to be of higher amplitude over the left, but there is some reflection of the activity on the left. D-3 is split between GPDs and GRDA. The ascending limb of the delta wave has a sharp morphology and there is asymmetry in slope between ascending and descending limbs making it an edge case. C-4 is split between LRDA and seizure. It shows 2Hz LRDA on the left, and the spectrogram shows that this segment may belong to the tail end of a seizure, an edge-case. D-4 is split between LRDA and GRDA. The rhythmic delta appears to be of higher amplitude over the left, but there is some reflection of the activity on the right. C-5 is split between GRDA and seizure. It shows potentially evolving rhythmic delta activity with poorly formed embedded epileptiform discharges, a pattern between GRDA and seizure, an edge-case. D-5 is split between GRDA and LPDs. There is generalized rhythmic delta activity, while the activity on the right is somewhat higher amplitude and contains poorly formed epileptiform discharges suggestive of LPDs, an edge-case. Note: Recording regions of the EEG electrodes are abbreviated as LL = left lateral; RL = right lateral; LP = left parasagittal; RP = right parasagittal.
+
+### Evaluation
+
+Submissions are evaluated on the [Kullback Liebler divergence](https://www.kaggle.com/code/metric/kullback-leibler-divergence/notebook) between the predicted probability and the observed target.
+
+#### Submission File
+
+For each `eeg_id` in the test set, you must predict a probability for each of the `vote` columns. The file should contain a header and have the following format:
+
+```
+eeg_id,seizure_vote,lpd_vote,gpd_vote,lrda_vote,grda_vote,other_vote\
+0,0.166,0.166,0.167,0.167,0.167,0.167\
+1,0.166,0.166,0.167,0.167,0.167,0.167\
+etc.
+```
+
+Your total predicted probabilities for each row must sum to one or your submission will fail.
+
+### Timeline
+
+- **January 8, 2024** - Start Date.
+- **April 1, 2024** - Entry Deadline. You must accept the competition rules before this date in order to compete.
+- **April 1, 2024** - Team Merger Deadline. This is the last day participants may join or merge teams.
+- **April 8, 2024** - Final Submission Deadline.
+
+Al deadlines are at 11:59 PM UTC on the corresponding day unless otherwise noted. The competition organizers reserve the right to update the contest timeline if they deem it necessary.
+
+### Prizes
+
+- 1st Place - \$20,000
+- 2nd Place - \$12,000
+- 3rd Place - \$7,000
+- 4th Place - \$6,000
+- 5th Place - \$5,000
+
+### Code Requirements
+
+![](https://storage.googleapis.com/kaggle-media/competitions/general/Kerneler-white-desc2_transparent.png)
+
+**This is a Code Competition**
+
+Submissions to this competition must be made through Notebooks. In order for the "Submit" button to be active after a commit, the following conditions must be met:
+
+- CPU Notebook `<= 9` hours run-time
+- GPU Notebook `<= 9` hours run-time
+- Internet access disabled
+- Freely & publicly available external data is allowed, including pre-trained models
+- Submission file must be named `submission.csv`
+
+Please see the [Code Competition FAQ](https://www.kaggle.com/docs/competitions#notebooks-only-FAQ) for more information on how to submit. And review the [code debugging doc](https://www.kaggle.com/code-competition-debugging) if you are encountering submission errors.
+
+### Acknowledgements
+
+![](https://storage.googleapis.com/kaggle-media/competitions/Harvard%20Medical%20School/CCEMRC-logo.gif)
+
+We gratefully acknowledge the work of the experts from the [Critical Care EEG Monitoring Research Consortium](https://www.acns.org/research/critical-care-eeg-monitoring-research-consortium-ccemrc) (CCEMRC), who provided the labels for model training and evaluation, and to others who contributed to the scientific work that enabled this competition. Specifically, we acknowledge the contributions of (numbers refer to institutional affiliations in the list below):
+
+Jin Jing^1,2^, Wendong Ge, Aaron F. Struck^3,4^ , Marta Bento Fernandes^1,2^, Shenda Hong^5^, Sungtae An^7^, Safoora Fatima^3^, Aline Herlopian^8^, Ioannis Karakis^9^, Jonathan J. Halford^10^, Marcus Ng^11^, Emily L. Johnson^12^, Brian Appavu^13^, Rani A. Sarkis^14^, Gamaleldin Osman^15^, Peter W. Kaplan^12^, Monica B. Dhakar^16^, Lakshman Arcot Jayagopal^17^, Zubeda Sheikh^18^, Olha Taraschenko^17^, Sarah Schmitt^10^, Hiba A. Haider^19^, Jennifer A. Kim^8^, Christa B. Swisher^20^, Nicolas Gaspard^21^, Mackenzie C. Cervenka^12^, Andres Rodriguez^9^, Jong Woo Lee^14^, Mohammad Tabaeizadeh^1,2^, Emily J. Gilmore^8^, Kristy Nordstrom^1^, Ji Yeoun Yoo^22^, Manisha Holmes^23^, Susan T. Herman^24^, Jennifer A. Williams^25^, Jay Pathmanathan^26^, Fábio A. Nascimento^1,2^, Ziwei Fan^1,2^, Samaneh Nasiri^1,2^, Mouhsin M. Shafi^27^, Sydney S. Cash^1,2^, Daniel B. Hoch^1,2^, Andrew J. Cole^1,2^, Eric S. Rosenthal^1,2^, Sahar F. Zafar^1,2^, Jimeng Sun^5^, M. Brandon Westover^1,2^
+
+1-Massachusetts General Hospital/Harvard Medical School Department of Neurology, MA\
+2-Massachusetts General Hospital Clinical Data Animation Center (CDAC), MA\
+3-University of Wisconsin-Madison Department of Neurology\
+4-William S Middleton Memorial Veterans Hospital Madison, WI\
+5-National Institute of Health Data Science, Peking University, Beijing, China\
+6-University of Illinois at Urbana-Champaign, College of Computing, Champaign, IL\
+7-Georgia Institute of Technology, College of Computing, Atlanta, GA\
+8-Yale University-Yale New Haven Hospital, CT\
+9-Emory University School of Medicine, GA\
+10-Medical University of South Carolina, SC\
+11-University of Manitoba, Canada\
+12-Johns Hopkins School of Medicine, MD\
+13-University of Arizona College of Medicine, AZ\
+14-Brigham and Women's Hospital, MA\
+15-Mayo Clinic-Rochester, MN\
+16-Warren Alpert School of Medicine of Brown University, Providence, RI\
+17-University of Nebraska Medical Center, NE\
+18-West Virginia University Hospitals, WV\
+19-University of Chicago, Chicago, IL\
+20-Atrium Health, NC\
+21-Université Libre de Bruxelles - Hôpital Erasme, Belgium\
+22-Icahn School of Medicine, Mount Sinai, NY\
+23-New York University (NYU) Grossman School of Medicine, NY\
+24-Barrow Neurological Institute, Phoenix, AZ\
+25-Mater Misericordiae University Hospital, Dublin, Ireland.\
+26-University of Pennsylvania, PA\
+27-Beth Israel Deaconess Medical Center/Harvard Medical School, MA
+
+### Citation
+
+Jin Jing, Zhen Lin, Chaoqi Yang, Ashley Chow, Sohier Dane, Jimeng Sun, M. Brandon Westover. (2024). HMS - Harmful Brain Activity Classification . Kaggle. https://kaggle.com/competitions/hms-harmful-brain-activity-classification
+
+# Data
+
+## Dataset Description
+
+The goal of this competition is to detect and classify seizures and other types of harmful brain activity in electroencephalography (EEG) data. Even experts find this to be a challenging task and often disagree about the correct labels.
+
+This is a code competition. Only a few examples from the test set are available for download. When your submission is scored the test folders will be replaced with versions containing the complete test set.
+
+### Files
+
+**train.csv** Metadata for the train set. The expert annotators reviewed 50 second long EEG samples plus matched spectrograms covering 10 a minute window centered at the same time and labeled the central 10 seconds. Many of these samples overlapped and have been consolidated. `train.csv` provides the metadata that allows you to extract the original subsets that the raters annotated.
+
+- `eeg_id` - A unique identifier for the entire EEG recording.
+- `eeg_sub_id` - An ID for the specific 50 second long subsample this row's labels apply to.
+- `eeg_label_offset_seconds` - The time between the beginning of the consolidated EEG and this subsample.
+- `spectrogram_id` - A unique identifier for the entire EEG recording.
+- `spectrogram_sub_id` - An ID for the specific 10 minute subsample this row's labels apply to.
+- `spectogram_label_offset_seconds` - The time between the beginning of the consolidated spectrogram and this subsample.
+- `label_id` - An ID for this set of labels.
+- `patient_id` - An ID for the patient who donated the data.
+- `expert_consensus` - The consensus annotator label. Provided for convenience only.
+- `[seizure/lpd/gpd/lrda/grda/other]_vote` - The count of annotator votes for a given brain activity class. The full names of the activity classes are as follows: `lpd`: lateralized periodic discharges, `gpd`: generalized periodic discharges, `lrd`: lateralized rhythmic delta activity, and `grda`: generalized rhythmic delta activity . A detailed explanations of these patterns is [available here.](https://www.acns.org/UserFiles/file/ACNSStandardizedCriticalCareEEGTerminology_rev2021.pdf)
+
+**test.csv** Metadata for the test set. As there are no overlapping samples in the test set, many columns in the train metadata don't apply.
+
+- `eeg_id`
+- `spectrogram_id`
+- `patient_id`
+
+**sample_submission.csv**
+
+- `eeg_id`
+- `[seizure/lpd/gpd/lrda/grda/other]_vote` - The target columns. Your predictions must be probabilities. Note that the test samples had between 3 and 20 annotators.
+
+**train_eegs/** EEG data from one or more overlapping samples. Use the metadata in train.csv to select specific annotated subsets. The column names are [the names of the individual electrode locations for EEG leads](https://en.wikipedia.org/wiki/10%E2%80%9320_system_%28EEG%29), with one exception. The EKG column is for an electrocardiogram lead that records data from the heart. All of the EEG data (for both train and test) was collected at a frequency of 200 samples per second.
+
+**test_eegs/** Exactly 50 seconds of EEG data.
+
+train_spectrograms/ Spectrograms assembled EEG data. Use the metadata in train.csv to select specific annotated subsets. The column names indicate the frequency in hertz and the recording regions of the EEG electrodes. The latter are abbreviated as LL = left lateral; RL = right lateral; LP = left parasagittal; RP = right parasagittal.
+
+**test_spectrograms/** Spectrograms assembled using exactly 10 minutes of EEG data.
+
+**example_figures/** Larger copies of the example case images used on the overview tab.

dslighting/registry/hms-harmful-brain-activity-classification/description_obfuscated.md

@@ -0,0 +1,56 @@
+# Task
+
+Detect and classify harmful brain activity in electroencephalography (EEG) data: seizure (SZ), generalized periodic discharges (GPD), lateralized periodic discharges (LPD), lateralized rhythmic delta activity (LRDA), generalized rhythmic delta activity (GRDA), or "other".
+
+# Metric
+
+Kullback Liebler divergence between the predicted probability and the observed target.
+
+# Submission Format
+
+For each `eeg_id` in the test set, you must predict a probability for each of the `vote` columns. The file should contain a header and have the following format:
+
+```
+eeg_id,seizure_vote,lpd_vote,gpd_vote,lrda_vote,grda_vote,other_vote\
+0,0.166,0.166,0.167,0.167,0.167,0.167\
+1,0.166,0.166,0.167,0.167,0.167,0.167\
+etc.
+```
+
+Your total predicted probabilities for each row must sum to one or your submission will fail.
+
+# Dataset
+
+**train.csv** Metadata for the train set. The expert annotators reviewed 50 second long EEG samples plus matched spectrograms covering 10 a minute window centered at the same time and labeled the central 10 seconds. Many of these samples overlapped and have been consolidated. `train.csv` provides the metadata that allows you to extract the original subsets that the raters annotated.
+
+- `eeg_id` - A unique identifier for the entire EEG recording.
+- `eeg_sub_id` - An ID for the specific 50 second long subsample this row's labels apply to.
+- `eeg_label_offset_seconds` - The time between the beginning of the consolidated EEG and this subsample.
+- `spectrogram_id` - A unique identifier for the entire EEG recording.
+- `spectrogram_sub_id` - An ID for the specific 10 minute subsample this row's labels apply to.
+- `spectogram_label_offset_seconds` - The time between the beginning of the consolidated spectrogram and this subsample.
+- `label_id` - An ID for this set of labels.
+- `patient_id` - An ID for the patient who donated the data.
+- `expert_consensus` - The consensus annotator label. Provided for convenience only.
+- `[seizure/lpd/gpd/lrda/grda/other]_vote` - The count of annotator votes for a given brain activity class. The full names of the activity classes are as follows: `lpd`: lateralized periodic discharges, `gpd`: generalized periodic discharges, `lrd`: lateralized rhythmic delta activity, and `grda`: generalized rhythmic delta activity . A detailed explanations of these patterns is [available here.](https://www.acns.org/UserFiles/file/ACNSStandardizedCriticalCareEEGTerminology_rev2021.pdf)
+
+**test.csv** Metadata for the test set. As there are no overlapping samples in the test set, many columns in the train metadata don't apply.
+
+- `eeg_id`
+- `spectrogram_id`
+- `patient_id`
+
+**sample_submission.csv**
+
+- `eeg_id`
+- `[seizure/lpd/gpd/lrda/grda/other]_vote` - The target columns. Your predictions must be probabilities. Note that the test samples had between 3 and 20 annotators.
+
+**train_eegs/** EEG data from one or more overlapping samples. Use the metadata in train.csv to select specific annotated subsets. The column names are [the names of the individual electrode locations for EEG leads](https://en.wikipedia.org/wiki/10%E2%80%9320_system_%28EEG%29), with one exception. The EKG column is for an electrocardiogram lead that records data from the heart. All of the EEG data (for both train and test) was collected at a frequency of 200 samples per second.
+
+**test_eegs/** Exactly 50 seconds of EEG data.
+
+train_spectrograms/ Spectrograms assembled EEG data. Use the metadata in train.csv to select specific annotated subsets. The column names indicate the frequency in hertz and the recording regions of the EEG electrodes. The latter are abbreviated as LL = left lateral; RL = right lateral; LP = left parasagittal; RP = right parasagittal.
+
+**test_spectrograms/** Spectrograms assembled using exactly 10 minutes of EEG data.
+
+**example_figures/** Larger copies of the example case images used on the overview tab.

dslighting/registry/hms-harmful-brain-activity-classification/grade.py

@@ -0,0 +1,43 @@
+import pandas as pd
+
+from mlebench.grade_helpers import InvalidSubmissionError
+
+from . import kullback_leibler_divergence as kl_divergence
+from .constants import ID_COL, TARGET_COLS
+
+
+def prepare_for_metric(submission: pd.DataFrame, answers: pd.DataFrame) -> tuple:
+
+    if ID_COL not in submission.columns:
+        raise InvalidSubmissionError(f"Submission must contain {ID_COL} column")
+    if not all(col in submission.columns for col in TARGET_COLS):
+        raise InvalidSubmissionError(f"Submission must contain all target columns: {TARGET_COLS}")
+    if len(submission) != len(answers):
+        raise InvalidSubmissionError("Submission and answers must have the same length")
+    if not (submission[TARGET_COLS].sum(axis=1).apply(lambda x: round(x, 5) == 1).all()):
+        raise InvalidSubmissionError("Submission probabilities must add to 1 for each row")
+    if not set(answers[ID_COL]) == set(submission[ID_COL]):
+        raise InvalidSubmissionError("Submission and answers must have the same IDs")
+
+    assert ID_COL in answers.columns, f"Answers must contain {ID_COL} column"
+    assert all(
+        col in answers.columns for col in TARGET_COLS
+    ), f"Answers must contain all target columns: {TARGET_COLS}"
+
+    submission = submission.sort_values(ID_COL).reset_index(drop=True)
+    answers = answers.sort_values(ID_COL).reset_index(drop=True)
+
+    answers = answers.copy()[[ID_COL] + TARGET_COLS]
+    # normalize answers to be max 1, by taking vote / sum(votes)
+    # https://www.kaggle.com/competitions/hms-harmful-brain-activity-classification/discussion/468705#2606605
+    answers[TARGET_COLS] = answers[TARGET_COLS].div(answers[TARGET_COLS].sum(axis=1), axis=0)
+
+    return submission, answers
+
+
+def grade(submission: pd.DataFrame, answers: pd.DataFrame) -> float:
+
+    submission, answers = prepare_for_metric(submission, answers)
+    score = kl_divergence.score(answers, submission, ID_COL)
+
+    return score

dslighting/registry/hms-harmful-brain-activity-classification/kaggle_metric_utilities.py

@@ -0,0 +1,96 @@
+"""
+This script exists to reduce code duplication across metrics.
+Source: https://www.kaggle.com/code/metric/kaggle-metric-utilities
+Linked from: https://www.kaggle.com/code/metric/kullback-leibler-divergence
+Linked from: https://www.kaggle.com/competitions/hms-harmful-brain-activity-classification
+"""
+
+from typing import Union
+
+import numpy as np
+import pandas as pd
+import pandas.api.types
+
+
+class ParticipantVisibleError(Exception):
+    pass
+
+
+class HostVisibleError(Exception):
+    pass
+
+
+def treat_as_participant_error(
+    error_message: str, solution: Union[pd.DataFrame, np.ndarray]
+) -> bool:
+    """Many metrics can raise more errors than can be handled manually. This function attempts
+    to identify errors that can be treated as ParticipantVisibleError without leaking any competition data.
+
+    If the solution is purely numeric, and there are no numbers in the error message,
+    then the error message is sufficiently unlikely to leak usable data and can be shown to participants.
+
+    We expect this filter to reject many safe messages. It's intended only to reduce the number of errors we need to manage manually.
+    """
+    # This check treats bools as numeric
+    if isinstance(solution, pd.DataFrame):
+        solution_is_all_numeric = all(
+            [pandas.api.types.is_numeric_dtype(x) for x in solution.dtypes.values]
+        )
+        solution_has_bools = any(
+            [pandas.api.types.is_bool_dtype(x) for x in solution.dtypes.values]
+        )
+    elif isinstance(solution, np.ndarray):
+        solution_is_all_numeric = pandas.api.types.is_numeric_dtype(solution)
+        solution_has_bools = pandas.api.types.is_bool_dtype(solution)
+
+    if not solution_is_all_numeric:
+        return False
+
+    for char in error_message:
+        if char.isnumeric():
+            return False
+    if solution_has_bools:
+        if "true" in error_message.lower() or "false" in error_message.lower():
+            return False
+    return True
+
+
+def safe_call_score(metric_function, solution, submission, **metric_func_kwargs):
+    """
+    Call score. If that raises an error and that already been specifically handled, just raise it.
+    Otherwise make a conservative attempt to identify potential participant visible errors.
+    """
+    try:
+        score_result = metric_function(solution, submission, **metric_func_kwargs)
+    except Exception as err:
+        error_message = str(err)
+        if err.__class__.__name__ == "ParticipantVisibleError":
+            raise ParticipantVisibleError(error_message)
+        elif err.__class__.__name__ == "HostVisibleError":
+            raise HostVisibleError(error_message)
+        else:
+            if treat_as_participant_error(error_message, solution):
+                raise ParticipantVisibleError(error_message)
+            else:
+                raise err
+    return score_result
+
+
+def verify_valid_probabilities(df: pd.DataFrame, df_name: str):
+    """Verify that the dataframe contains valid probabilities.
+
+    The dataframe must be limited to the target columns; do not pass in any ID columns.
+    """
+    if not pandas.api.types.is_numeric_dtype(df.values):
+        raise ParticipantVisibleError(f"All target values in {df_name} must be numeric")
+
+    if df.min().min() < 0:
+        raise ParticipantVisibleError(f"All target values in {df_name} must be at least zero")
+
+    if df.max().max() > 1:
+        raise ParticipantVisibleError(f"All target values in {df_name} must be no greater than one")
+
+    if not np.allclose(df.sum(axis=1), 1):
+        raise ParticipantVisibleError(
+            f"Target values in {df_name} do not add to one within all rows"
+        )