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

dslighting/registry/vinbigdata-chest-xray-abnormalities-detection/grade.py

@@ -0,0 +1,220 @@
+import numpy as np
+import pandas as pd
+from pycocotools.coco import COCO
+from pycocotools.cocoeval import COCOeval
+
+from mlebench.grade_helpers import InvalidSubmissionError
+
+
+def prepare_for_metric(submission: pd.DataFrame, answers: pd.DataFrame) -> dict:
+    """Prepare the submission and answers for the metric."""
+
+    required_answer_columns = ["class_id", "x_min", "y_min", "x_max", "y_max", "image_id"]
+    for col in required_answer_columns:
+        assert col in answers.columns, f"Answers must have a `{col}` column"
+    for col in ["x_min", "y_min", "x_max", "y_max"]:
+        assert (
+            not answers[col].isnull().values.any()
+        ), f"Answers must not contain any NaN values in `{col}` column, but got {answers[col].isnull().values}"
+
+    required_submission_columns = ["PredictionString", "image_id"]
+    for col in required_submission_columns:
+        if col not in submission.columns:
+            raise InvalidSubmissionError(f"Submission must have a `{col}` column")
+
+    if set(submission["image_id"]) != set(answers["image_id"]):
+        raise InvalidSubmissionError(
+            "The set of image_ids in the submission must match the set of image_ids in the answers"
+        )
+
+    return {"true_df": answers, "pred_df": submission}
+
+
+def grade(submission: pd.DataFrame, answers: pd.DataFrame) -> float:
+    inputs = prepare_for_metric(submission, answers)
+    vineval = VinBigDataEval(inputs["true_df"])
+    cocoEvalResults = vineval.evaluate(inputs["pred_df"])
+    return cocoEvalResults.stats[0]
+
+
+class VinBigDataEval:
+    """Helper class for calculating the competition metric.
+
+    You should remove the duplicated annoatations from the `true_df` dataframe
+    before using this script. Otherwise it may give incorrect results.
+
+        >>> vineval = VinBigDataEval(valid_df)
+        >>> cocoEvalResults = vineval.evaluate(pred_df)
+
+    Arguments:
+        true_df: pd.DataFrame Clean (no duplication) Training/Validating dataframe.
+
+    Authors:
+        Peter (https://kaggle.com/pestipeti)
+
+    See:
+        https://www.kaggle.com/pestipeti/competition-metric-map-0-4
+
+    Returns: None
+
+    """
+
+    def __init__(self, true_df):
+
+        self.true_df = true_df
+
+        self.image_ids = true_df["image_id"].unique()
+        self.annotations = {
+            "type": "instances",
+            "images": self.__gen_images(self.image_ids),
+            "categories": self.__gen_categories(self.true_df),
+            "annotations": self.__gen_annotations(self.true_df, self.image_ids),
+        }
+
+        self.predictions = {
+            "images": self.annotations["images"].copy(),
+            "categories": self.annotations["categories"].copy(),
+            "annotations": None,
+        }
+
+    def __gen_categories(self, df):
+        print("Generating category data...")
+
+        if "class_name" not in df.columns:
+            df["class_name"] = df["class_id"]
+
+        cats = df[["class_name", "class_id"]]
+        cats = cats.drop_duplicates().sort_values(by="class_id").values
+
+        results = []
+
+        for cat in cats:
+            results.append(
+                {
+                    "id": cat[1],
+                    "name": cat[0],
+                    "supercategory": "none",
+                }
+            )
+
+        return results
+
+    def __gen_images(self, image_ids):
+        print("Generating image data...")
+        results = []
+
+        for idx, image_id in enumerate(image_ids):
+
+            # Add image identification.
+            results.append(
+                {
+                    "id": idx,
+                }
+            )
+
+        return results
+
+    def __gen_annotations(self, df, image_ids):
+        print("Generating annotation data...")
+        k = 0
+        results = []
+
+        for idx, image_id in enumerate(image_ids):
+
+            # Add image annotations
+            for i, row in df[df["image_id"] == image_id].iterrows():
+
+                results.append(
+                    {
+                        "id": k,
+                        "image_id": idx,
+                        "category_id": row["class_id"],
+                        "bbox": np.array([row["x_min"], row["y_min"], row["x_max"], row["y_max"]]),
+                        "segmentation": [],
+                        "ignore": 0,
+                        "area": (row["x_max"] - row["x_min"]) * (row["y_max"] - row["y_min"]),
+                        "iscrowd": 0,
+                    }
+                )
+
+                k += 1
+
+        return results
+
+    def __decode_prediction_string(self, pred_str):
+        data = list(map(float, pred_str.split(" ")))
+        data = np.array(data)
+
+        return data.reshape(-1, 6)
+
+    def __gen_predictions(self, df, image_ids):
+        print("Generating prediction data...")
+        k = 0
+        results = []
+
+        for i, row in df.iterrows():
+
+            image_id = row["image_id"]
+            preds = self.__decode_prediction_string(row["PredictionString"])
+
+            for j, pred in enumerate(preds):
+
+                results.append(
+                    {
+                        "id": k,
+                        "image_id": int(np.where(image_ids == image_id)[0]),
+                        "category_id": int(pred[0]),
+                        "bbox": np.array([pred[2], pred[3], pred[4], pred[5]]),
+                        "segmentation": [],
+                        "ignore": 0,
+                        "area": (pred[4] - pred[2]) * (pred[5] - pred[3]),
+                        "iscrowd": 0,
+                        "score": pred[1],
+                    }
+                )
+
+                k += 1
+
+        return results
+
+    def evaluate(self, pred_df, n_imgs=-1):
+        """Evaluating your results
+
+        Arguments:
+            pred_df: pd.DataFrame your predicted results in the
+                     competition output format.
+
+            n_imgs:  int Number of images use for calculating the
+                     result.All of the images if `n_imgs` <= 0
+
+        Returns:
+            COCOEval object
+        """
+
+        if pred_df is not None:
+            self.predictions["annotations"] = self.__gen_predictions(pred_df, self.image_ids)
+
+        coco_ds = COCO()
+        coco_ds.dataset = self.annotations
+        coco_ds.createIndex()
+
+        coco_dt = COCO()
+        coco_dt.dataset = self.predictions
+        coco_dt.createIndex()
+
+        imgIds = sorted(coco_ds.getImgIds())
+
+        if n_imgs > 0:
+            imgIds = np.random.choice(imgIds, n_imgs)
+
+        cocoEval = COCOeval(coco_ds, coco_dt, "bbox")
+        cocoEval.params.imgIds = imgIds
+        cocoEval.params.useCats = True
+        cocoEval.params.iouType = "bbox"
+        cocoEval.params.iouThrs = np.array([0.4])
+
+        cocoEval.evaluate()
+        cocoEval.accumulate()
+        cocoEval.summarize()
+
+        return cocoEval

dslighting/registry/vinbigdata-chest-xray-abnormalities-detection/prepare.py

@@ -0,0 +1,129 @@
+import shutil
+from pathlib import Path
+
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from tqdm import tqdm
+
+from mlebench.utils import read_csv
+
+
+def prepare(raw: Path, public: Path, private: Path):
+    """
+    Splits the data in raw into public and private datasets with appropriate test/train splits.
+    """
+
+    dev = False
+
+    # Create train, test from train split
+    old_train = read_csv(raw / "train.csv")
+    unique_image_ids = old_train["image_id"].unique()
+    # Original train has 15k images, original test has 3k images
+    # Our new train will have 13.5k images, our new test will have 1.5k images
+    expected_train_size = 13500
+    expected_test_size = 1500
+    train_image_ids, test_image_ids = train_test_split(
+        unique_image_ids, test_size=0.1, random_state=0
+    )
+
+    new_train = old_train[old_train["image_id"].isin(train_image_ids)]
+    answers = old_train[old_train["image_id"].isin(test_image_ids)]
+
+    # Create sample submission
+    sample_submission = pd.DataFrame(
+        {
+            "image_id": test_image_ids,
+            "PredictionString": "14 1 0 0 1 1",
+        }  # As per the original sample submission
+    )
+
+    # Checks
+    assert (
+        len(set(new_train["image_id"])) == expected_train_size
+    ), f"Expected {expected_train_size} train image_ids, got {len(set(new_train['image_id']))}"
+    assert (
+        len(set(answers["image_id"])) == expected_test_size
+    ), f"Expected {expected_test_size} test image_ids, got {len(set(answers['image_id']))}"
+    assert set(new_train["image_id"]).isdisjoint(
+        set(answers["image_id"])
+    ), f"image_id is not disjoint between train and test sets"
+    assert (
+        new_train.columns.tolist() == old_train.columns.tolist()
+    ), f"Columns of new train and old train are not the same: {new_train.columns.tolist()} vs {old_train.columns.tolist()}"
+    assert len(new_train) + len(answers) == len(
+        old_train
+    ), f"Length of new train and answers should add up to the length of old train, got {len(new_train) + len(answers)} vs {len(old_train)}"
+    assert len(sample_submission) == len(
+        set(answers["image_id"])
+    ), f"Length of sample submission should be equal to the number of unique image_ids in answers, got {len(sample_submission)} vs {len(set(answers['image_id']))}"
+
+    # Reformat answers
+    def _get_consensus_annotation(answers, inspect_duplicates=False):
+        """
+        In the original train, there can be multiple annotations of the same image_id, class_id pair. (Different radiologists draw the bounding boxes differently for the same finding)
+
+        In the original test, there is only one annotation per image_id, class_id pair. The original test set is labeled by consensus of 5 radiologists. (Source: https://www.kaggle.com/competitions/vinbigdata-chest-xray-abnormalities-detection/discussion/207969#1134645)
+
+        We simulate consensus by taking the first annotation for each image_id, class_id pair.
+        """
+
+        if inspect_duplicates:
+            duplicates = answers[answers.duplicated(subset=["image_id", "class_id"], keep=False)]
+            duplicates = duplicates.sort_values(by=["image_id", "class_id"])
+            duplicates.to_csv("duplicates.csv", index=False)
+
+        answers = answers.groupby(by=["image_id", "class_id"]).first().reset_index()
+        return answers
+
+    answers = _get_consensus_annotation(answers)
+    # Filling in missing values for when there is no finding (class_id = 14)
+    answers = answers.fillna(0)
+    answers.loc[answers["class_id"] == 14, ["x_max", "y_max"]] = 1.0
+
+    # Create gold submission
+    gold = answers[["image_id", "class_id", "x_min", "y_min", "x_max", "y_max"]].copy()
+    # Create individual prediction strings
+    gold.loc[:, "PredictionString"] = gold.apply(
+        lambda row: f"{row['class_id']} 1.0 {row['x_min']} {row['y_min']} {row['x_max']} {row['y_max']}",
+        axis=1,  # 1.0 is the confidence score
+    )
+    # Group by image_id and concatenate prediction strings
+    gold = gold.groupby("image_id")["PredictionString"].agg(" ".join).reset_index()
+    gold = gold.reset_index(drop=True)
+    assert len(gold) == len(
+        set(answers["image_id"])
+    ), f"Length of gold should be equal to the number of unique image_ids in answers, got {len(gold)} vs {len(set(answers['image_id']))}"
+
+    # Write CSVs
+    new_train.to_csv(public / "train.csv", index=False)
+    sample_submission.to_csv(public / "sample_submission.csv", index=False)
+    answers.to_csv(private / "answers.csv", index=False)
+    gold.to_csv(private / "gold_submission.csv", index=False)
+
+    # Copy over files
+    (public / "test").mkdir(exist_ok=True)
+    (public / "train").mkdir(exist_ok=True)
+
+    if dev == True:
+        train_image_ids = train_image_ids[:10]
+        test_image_ids = test_image_ids[:10]
+
+    for file_id in tqdm(train_image_ids, desc="Copying train files"):
+        shutil.copyfile(
+            src=raw / "train" / f"{file_id}.dicom",
+            dst=public / "train" / f"{file_id}.dicom",
+        )
+
+    for file_id in tqdm(test_image_ids, desc="Copying test files"):
+        shutil.copyfile(
+            src=raw / "train" / f"{file_id}.dicom",
+            dst=public / "test" / f"{file_id}.dicom",
+        )
+
+    # Check files
+    assert len(list(public.glob("train/*.dicom"))) == len(
+        train_image_ids
+    ), f"Expected {len(train_image_ids)} train files, got {len(list(public.glob('train/*.dicom')))}"
+    assert len(list(public.glob("test/*.dicom"))) == len(
+        test_image_ids
+    ), f"Expected {len(test_image_ids)} test files, got {len(list(public.glob('test/*.dicom')))}"

dslighting/registry/vinbigdata-chest-xray-abnormalities-detection/prepare_val.py

@@ -0,0 +1,204 @@
+import shutil
+from pathlib import Path
+
+import pandas as pd
+from sklearn.model_selection import train_test_split
+from tqdm import tqdm
+
+from mlebench.utils import read_csv
+
+
+def _get_consensus_annotation(answers, inspect_duplicates=False):
+    """
+    In the original train, there can be multiple annotations of the same image_id, class_id pair. (Different radiologists draw the bounding boxes differently for the same finding)
+
+    In the original test, there is only one annotation per image_id, class_id pair. The original test set is labeled by consensus of 5 radiologists. (Source: https://www.kaggle.com/competitions/vinbigdata-chest-xray-abnormalities-detection/discussion/207969#1134645)
+
+    We simulate consensus by taking the first annotation for each image_id, class_id pair.
+    """
+
+    if inspect_duplicates:
+        duplicates = answers[answers.duplicated(subset=["image_id", "class_id"], keep=False)]
+        duplicates = duplicates.sort_values(by=["image_id", "class_id"])
+        duplicates.to_csv("duplicates.csv", index=False)
+
+    answers = answers.groupby(by=["image_id", "class_id"]).first().reset_index()
+    return answers
+
+
+def _create_split_files(
+    train_df: pd.DataFrame,
+    answers_df: pd.DataFrame,
+    train_image_ids: list,
+    test_image_ids: list,
+    public_path: Path,
+    private_path: Path,
+    raw_images_path: Path,
+    dev: bool = False,
+):
+    """
+    Helper function to process and save a single train/test split to the specified paths.
+    This encapsulates the logic for creating submissions, writing CSVs, and copying image files.
+    """
+    public_path.mkdir(parents=True, exist_ok=True)
+    private_path.mkdir(parents=True, exist_ok=True)
+
+    # Create sample submission for the test set
+    sample_submission = pd.DataFrame(
+        {
+            "image_id": test_image_ids,
+            "PredictionString": "14 1 0 0 1 1",  # As per the original sample submission
+        }
+    )
+
+    # Reformat answers
+    answers = _get_consensus_annotation(answers_df)
+    # Filling in missing values for when there is no finding (class_id = 14)
+    answers = answers.fillna(0)
+    answers.loc[answers["class_id"] == 14, ["x_max", "y_max"]] = 1.0
+
+    # Create gold submission
+    gold = answers[["image_id", "class_id", "x_min", "y_min", "x_max", "y_max"]].copy()
+    # Create individual prediction strings
+    gold.loc[:, "PredictionString"] = gold.apply(
+        lambda row: f"{row['class_id']} 1.0 {row['x_min']} {row['y_min']} {row['x_max']} {row['y_max']}",
+        axis=1,  # 1.0 is the confidence score
+    )
+    # Group by image_id and concatenate prediction strings
+    gold = gold.groupby("image_id")["PredictionString"].agg(" ".join).reset_index()
+    gold = gold.reset_index(drop=True)
+
+    # Checks for this split
+    assert len(set(train_df["image_id"])) == len(
+        train_image_ids
+    ), f"Number of unique image_ids in train_df does not match the provided list for {public_path.name}"
+    assert len(set(answers["image_id"])) == len(
+        test_image_ids
+    ), f"Number of unique image_ids in answers does not match the provided list for {public_path.name}"
+    assert set(train_df["image_id"]).isdisjoint(
+        set(answers["image_id"])
+    ), f"image_id is not disjoint between train and test sets for {public_path.name}"
+    assert len(sample_submission) == len(
+        set(answers["image_id"])
+    ), f"Length of sample submission is incorrect for {public_path.name}"
+    assert len(gold) == len(
+        set(answers["image_id"])
+    ), f"Length of gold submission is incorrect for {public_path.name}"
+
+    # Write CSVs
+    train_df.to_csv(public_path / "train.csv", index=False)
+    sample_submission.to_csv(public_path / "sample_submission.csv", index=False)
+    answers.to_csv(private_path / "answers.csv", index=False)
+    gold.to_csv(private_path / "gold_submission.csv", index=False)
+
+    # Copy over files
+    (public_path / "test").mkdir(exist_ok=True)
+    (public_path / "train").mkdir(exist_ok=True)
+
+    if dev:
+        train_image_ids = train_image_ids[:10]
+        test_image_ids = test_image_ids[:10]
+
+    for file_id in tqdm(train_image_ids, desc=f"Copying {public_path.name} train files"):
+        shutil.copyfile(
+            src=raw_images_path / "train" / f"{file_id}.dicom",
+            dst=public_path / "train" / f"{file_id}.dicom",
+        )
+
+    for file_id in tqdm(test_image_ids, desc=f"Copying {public_path.name} test files"):
+        shutil.copyfile(
+            src=raw_images_path / "train" / f"{file_id}.dicom",
+            dst=public_path / "test" / f"{file_id}.dicom",
+        )
+
+    # Check files
+    assert len(list(public_path.glob("train/*.dicom"))) == len(
+        train_image_ids
+    ), f"Incorrect number of train files copied for {public_path.name}"
+    assert len(list(public_path.glob("test/*.dicom"))) == len(
+        test_image_ids
+    ), f"Incorrect number of test files copied for {public_path.name}"
+
+
+def prepare(raw: Path, public: Path, private: Path):
+    """
+    Splits the data in raw into public and private datasets with appropriate test/train splits.
+    Also creates a parallel validation split (public_val, private_val).
+    """
+
+    dev = False
+
+    # Create train, test from train split
+    old_train = read_csv(raw / "train.csv")
+    unique_image_ids = old_train["image_id"].unique()
+
+    # --- 1. Original Train/Test Split ---
+    # Original train has 15k images, original test has 3k images
+    # Our new train will have 13.5k images, our new test will have 1.5k images
+    expected_train_size = 13500
+    expected_test_size = 1500
+    train_image_ids, test_image_ids = train_test_split(
+        unique_image_ids, test_size=0.1, random_state=0
+    )
+
+    new_train = old_train[old_train["image_id"].isin(train_image_ids)]
+    answers = old_train[old_train["image_id"].isin(test_image_ids)]
+
+    # Checks
+    assert (
+        len(set(new_train["image_id"])) == expected_train_size
+    ), f"Expected {expected_train_size} train image_ids, got {len(set(new_train['image_id']))}"
+    assert (
+        len(set(answers["image_id"])) == expected_test_size
+    ), f"Expected {expected_test_size} test image_ids, got {len(set(answers['image_id']))}"
+    assert set(new_train["image_id"]).isdisjoint(
+        set(answers["image_id"])
+    ), f"image_id is not disjoint between train and test sets"
+    assert len(new_train) + len(answers) == len(
+        old_train
+    ), f"Length of new train and answers should add up to the length of old train, got {len(new_train) + len(answers)} vs {len(old_train)}"
+
+    # Create all files for the original public/private split
+    _create_split_files(
+        train_df=new_train,
+        answers_df=answers,
+        train_image_ids=train_image_ids,
+        test_image_ids=test_image_ids,
+        public_path=public,
+        private_path=private,
+        raw_images_path=raw,
+        dev=dev,
+    )
+
+    # --- 2. New Validation Split (from the `new_train` set) ---
+    print("\nCreating validation split...")
+
+    # Define paths for the new validation set
+    public_val = public.parent / "public_val"
+    private_val = private.parent / "private_val"
+
+    # The new validation set should have the same size as the original test set
+    train_for_val_split_ids = new_train["image_id"].unique()
+    val_test_size = expected_test_size / len(train_for_val_split_ids)
+
+    # Split `new_train` again to create a smaller train set and a validation set
+    # We use the same random_state for consistency in splitting methodology
+    train_val_image_ids, test_val_image_ids = train_test_split(
+        train_for_val_split_ids, test_size=val_test_size, random_state=0
+    )
+
+    train_val = new_train[new_train["image_id"].isin(train_val_image_ids)]
+    answers_val = new_train[new_train["image_id"].isin(test_val_image_ids)]
+
+    # Create all files for the new validation split
+    _create_split_files(
+        train_df=train_val,
+        answers_df=answers_val,
+        train_image_ids=train_val_image_ids,
+        test_image_ids=test_val_image_ids,
+        public_path=public_val,
+        private_path=private_val,
+        raw_images_path=raw,
+        dev=dev,
+    )
+    print("Validation split created successfully.")

dslighting/registry/whale-categorization-playground/checksums.yaml

@@ -0,0 +1,6 @@
+private:
+  test.csv: c86022f990b9fccf644806e023d24b51
+public:
+  sample_submission.csv: 6ca155a2486ee7455662e159318b09df
+  train.csv: fe97ca1df1ac09c8c3c6a24853481f79
+zip: 1fc460b6656261ddafcc21a44248844e

dslighting/registry/whale-categorization-playground/config.yaml

@@ -0,0 +1,16 @@
+id: whale-categorization-playground
+name: Humpback Whale Identification Challenge
+competition_type: simple
+awards_medals: false
+prizes: null
+description: mlebench/competitions/whale-categorization-playground/description.md
+
+dataset:
+  answers: whale-categorization-playground/prepared/private/test.csv
+  sample_submission: whale-categorization-playground/prepared/public/sample_submission.csv
+
+grader:
+  name: MAP@5
+  grade_fn: mlebench.competitions.whale-categorization-playground.grade:grade
+
+preparer: mlebench.competitions.whale-categorization-playground.prepare:prepare

dslighting/registry/whale-categorization-playground/description.md

@@ -0,0 +1,51 @@
+# Overview
+
+## Description
+
+![happy-whale](https://storage.googleapis.com/kaggle-media/competitions/kaggle/3333/media/happy-whale.jpg)
+
+After centuries of intense whaling, recovering whale populations still have a hard time adapting to warming oceans and struggle to compete every day with the industrial fishing industry for food.
+
+To aid whale conservation efforts, scientists use photo surveillance systems to monitor ocean activity. They use the shape of whales’ tails and unique markings found in footage to identify what species of whale they’re analyzing and meticulously log whale pod dynamics and movements. For the past 40 years, most of this work has been done manually by individual scientists, leaving a huge trove of data untapped and underutilized.
+
+In this competition, you’re challenged to build an algorithm to identifying whale species in images. You’ll analyze Happy Whale’s database of over 25,000 images, gathered from research institutions and public contributors. By contributing, you’ll help to open rich fields of understanding for marine mammal population dynamics around the globe.
+
+We'd like to thank [Happy Whale](https://happywhale.com/) for providing this data and problem. Happy Whale is a platform that uses image process algorithms to let anyone to submit their whale photo and have it automatically identified.
+
+## Evaluation
+
+Submissions are evaluated according to the Mean Average Precision @ 5 (MAP@5):
+
+$$
+MAP@5=\frac{1}{U} \sum_{u=1}^U \sum_{k=1}^{\min (n .5)} P(k)
+$$
+
+where `U` is the number of images, `P(k)` is the precision at cutoff `k`, and `n` is the number predictions per image.
+
+### Submission File
+
+For each `Image` in the test set, you may predict up to 5 labels for the whale `Id`. Whales that are not predicted to be one of the labels in the training data should be labeled as `new_whale`. The file should contain a header and have the following format:
+
+```
+Image,Id
+00029b3a.jpg,new_whale w_1287fbc w_98baff9 w_7554f44 w_1eafe46
+0003c693.jpg,new_whale w_1287fbc w_98baff9 w_7554f44 w_1eafe46
+...
+```
+
+## Citation
+
+Addison Howard, inversion, Ken Southerland, Ted Cheeseman. (2018). Humpback Whale Identification Challenge. Kaggle. https://kaggle.com/competitions/whale-categorization-playground
+
+# Data
+
+## Dataset Description
+
+This training data contains thousands of images of humpback whale flukes. Individual whales have been identified by researchers and given an `Id`. The challenge is to predict the whale `Id` of images in the test set. What makes this such a challenge is that there are only a few examples for each of 3,000+ whale Ids.
+
+## File descriptions
+
+- **train.zip** - a folder containing the training images
+- **train.csv** - maps the training `Image` to the appropriate whale `Id`. Whales that are not predicted to have a label identified in the training data should be labeled as `new_whale`.
+- **test.zip** - a folder containing the test images to predict the whale `Id`
+- **sample_submission.csv** - a sample submission file in the correct format

dslighting/registry/whale-categorization-playground/description_obfuscated.md

@@ -0,0 +1,27 @@
+# Task
+
+Predict the individual whale species in images.
+
+# Metric
+
+Mean Average Precision @ 5 (MAP@5).
+
+# Submission Format
+
+For each `Image` in the test set, you may predict up to 5 labels for the whale `Id`. Whales that are not predicted to be one of the labels in the training data should be labeled as `new_whale`. The file should contain a header and have the following format:
+
+```
+Image,Id
+00029b3a.jpg,new_whale w_1287fbc w_98baff9 w_7554f44 w_1eafe46
+0003c693.jpg,new_whale w_1287fbc w_98baff9 w_7554f44 w_1eafe46
+...
+```
+
+# Dataset
+
+This training data contains thousands of images of humpback whale flukes. Individual whales have been identified by researchers and given an `Id`. The challenge is to predict the whale `Id` of images in the test set. What makes this such a challenge is that there are only a few examples for each of 3,000+ whale Ids.
+
+- **train.zip** - a folder containing the training images
+- **train.csv** - maps the training `Image` to the appropriate whale `Id`. Whales that are not predicted to have a label identified in the training data should be labeled as `new_whale`.
+- **test.zip** - a folder containing the test images to predict the whale `Id`
+- **sample_submission.csv** - a sample submission file in the correct format