explaining the data and data stream creating notebook

README.md

@@ -1,3 +1,7 @@
 This Repository contains a folder called avalanche which is basically a fork from the avalanche framework at the 18.8.2021 (checkout bcba08cf4c8297f7060302b52fcbadbb7fde3a41) by ContinualAI found here: 
 
 https://github.com/ContinualAI/avalanche
+
+Further the camera trap data used and the way it was handled is described. The corresponding jupyter notbook is found in scripts/jupyter-notebooks
+
+

data/README.md

@@ -0,0 +1,24 @@
+# Explaining the Data
+
+## Raw Data 
+
+The raw data used to create the streams are found in the raw\_data\_csv\_files/ directory in form of csv files with meta-data columns. The data for the bavarian forest is found in all\_data\_MD.csv. The 'series\_code' column gives every series of images (sometimes refered to as sequences) a unique identifier. The cameratraps take five images at a time, checks for movement and then takes another five images until no more movement is detected. This means that the length of the series differ. The 'broken' column was created checking which images are truncated or broken in some shape or form. When we recieved the data from the biologists they only labeled every fifth image of a sequence. Further the only labeled those series containing at least on image with an animal. we used this information to extrapolate to an entire sequence. The 'in\_csv\_file' column indicates wheather that image was contained in the original file. The 'orig\_label' column is wrong and should be ignored, use the 'species' column for class names. The 'MD\_category' column contains the classification of the most confident bounding box of the mega detector. The mega detector only destinguisches between humans (2), vehicles (3) and animals (1). The images where the mega detector did not detect anything are labeled with -1 in that column. The 'MD\_max\_conf' column contains the highest confidence level found for the bounding boxes detected while the 'MD\_all\_conf' contains a list in string format of all confidences, which also indicates the number of bounding boxes detected.
+The all\_data\_Caltech.csv file was created from the original meta data json-files and contain similar columns as all\_data\_MD.csv. 
+The all\_data\_BB.csv files contain the meta data for the subset of the Brandenburg dataset that can be found in /AMMOD\_data/camera\_traps/Brandenburg/crops\_tilo. 
+
+
+## Label Dictionaries
+
+This folder contains pickled dictionary files, that map an integer label to a human readable species name. The bavarian forrest related dictionary used in all recent experiments is 'BIRDS\_11\_Species.pkl'. The earlier version, befrore two more classes were filtered out for beeing too small is found in 'BIRDS.pkl'. The word 'BIRDS' comes up in these file names because all the different fine-grained labels in the original csv 
+file we recieved from the biologists were joined to form a larger 'birds' class. The 'BB.pkl' is the Brandenburg dataset label dictionary, while the dictionary related to the Caltech camera trap dataset is found in CALTECH\_LABEL\_DICT.pkl. 
+
+ 
+## Stream Files
+
+The streams were created with the data\_stream\_creation notebook found in /scripts/jupyter\_notbeooks/. 
+In the folder BW\_stream\_files there are the files for the bavarian forest data, Bayerischer Wald (BW), while the Caltech\_stram\_files contains the data for the Caltech data. 
+In each of these folders there are files corresponding to each of the five cross-validation splits. The affiliations are indicated by the 'cvi\_' at the beginning of each file name. For each split, two-thirds of the data are used for training, one third is used in the test data and the last third is used as validation data. The data is split series- and class-wise. This means that images from one series will all be placed in one of the three groups train/test/validation. Further, the series for each class where split into five sets  used to creat the cross-validation splits which means that the share of images from each class is roughly the same for all train/test/validation data. Because the sereis differ in length, this is only roughly the case though. 
+For each split there is a train\_stream, test\_stream and validation\_stream. The train\_stream files contain a list of sublists which contian tuple of with the following fields (img\_path, int\_label, seq\_id). Each sublist is also called an experience, a term introduced by avalanche, and is either 128 or 384 tupel long. The data strem with experience 384 contains the exact same data as the corresponding stream with experience size 128. The experiences where simply joined together, therfore the test and validation data remains the same. The train streams are ordered by date and series code. This means the first experience contains the series of the earlies data in the dataset. In order to fit the fixed experience size, a single sequence might have been split across two experiences in a row. The test and validation files contain a single list with tupels of the same shape. The test/validation files with either 'summer' or 'winter' in the filename are the subsets of the full test/validation files corresponding to a specific season. We defined two months before and three after the summer solstice as summer. Each of the described files also comes in a '\_crop\_' version, where the image path in the tupel differs from the non-crop version. In our experiments only one cropped image with the highest conidence produced by the mega detector was extracted and used. Preliminary experiments showed the benefit of using the cropped image in terms of classification accuracy, which is why we used the crops onyl in the experiments. The 'exp\_season\_split\_dict.pkl' files are dictionaries with the keys 'summer' and 'winter' which each have lists as values that indicate which experience belongs to which season of the stream with experience size 128. When using the data with expereince size 384 this has to be considered. 
+
+
+