From f9efeef08a7cffab5cb76f8f67ec509c7144a642 Mon Sep 17 00:00:00 2001 From: Sammy Date: Sun, 30 Nov 2025 20:51:58 -0500 Subject: [PATCH 1/2] will update documentation --- docs/CONFIGURING_DATAVALIDATION.md | 62 +++++++++++------------ docs/QUICK_START.md | 79 +++++++++++++++++++----------- docs/WHAT_IS_FALCONSCOUT.md | 4 +- 3 files changed, 84 insertions(+), 61 deletions(-) diff --git a/docs/CONFIGURING_DATAVALIDATION.md b/docs/CONFIGURING_DATAVALIDATION.md index 9799095..a31adec 100644 --- a/docs/CONFIGURING_DATAVALIDATION.md +++ b/docs/CONFIGURING_DATAVALIDATION.md @@ -9,14 +9,14 @@ To configure datavalidation you only need to edit a couple fields in the `config Example: ``` -year: 2022 -event_code: "iri" +year: 2025 +event_code: "bob" ``` ### Required Configuration Fields - `year` - - specifies the year the competition is taking place(i.e. 2023) + - specifies the year the competition is taking place(i.e. 2026) - `event_code` - a string, written in all lowercase letters, which corresponds to the given event and can be found on TBA (i.e. 'iri', 'cmptx') @@ -24,15 +24,15 @@ Additionally, a json file must exist in the `backend/data` directory in the form ### Optional Configuration Fields - `run_with_tba` - - determines whether match schedule will be retrieved from tba or from file, also determines if checks based on TBA data will run + - determines whether match schedule will be retrieved from tba or from file, also determines if checks based on TBA (The Blue Alliance) data will run - default: `true` ### Match Schedule Configuration -A couple of the checks in the datavalidation software rely having access to an accurate match schedule. These checks are important since they ensure that the data collected corresponds to the correct team number. +A couple of the checks in the datavalidation software rely on having access to an accurate match schedule. These checks are important since they ensure that the data collected corresponds to the correct team number. -By default the software will attempt to retrieve the match schedule using TBA's api. However, at smaller competitions its possible that TBA may not have a copy of match schedule ready in time for the competition. In that case the scouting admin is able to edit a copy of the match schedule by hand. +By default, the software will attempt to retrieve the match schedule using TBA's api. However, at smaller competitions its possible that TBA may not have a copy of match schedule ready in time for the competition. In that case the scouting admin is able to edit a copy of the match schedule by hand. -To do this the `run_with_tba` configuration field must be specified as `false` in the `config.yaml` file. The `../data/match_schedule.json` file, which currently contains the match schedule from `2022iri`, can then be edited. +To do this the `run_with_tba` configuration field must be specified as `false` in the `config.yaml` file. The `../data/match_schedule.json` file, which currently contains the match schedule from `2024ash`, can then be edited. ### Making DataValidation Optional @@ -41,10 +41,10 @@ Datavalidation uses inheritance to provide teams with some level of base functio - `BaseDataValidation` Class - At the heart of the DataValidation software is a class called `BaseDataValidation`. This class contains basic checks which are essential to validating data from any scouting app(i.e. match schedule checks, defense checks). - It also includes two important abstract methods `validate_data` and `validate_submission`, these two methods must be implimented in any child class and are where other checks are called from. -- `DataValidation2022` Child Class +- `DataValidation2025` Child Class - Inherits `BaseDataValidation` ``` - class DataValidation2022(BaseDataValidation): + class DataValidation2025(BaseDataValidation): def __init__(self, path_to_config: str = "config yaml"): super().__init__(path_to_config) ``` @@ -58,20 +58,19 @@ Datavalidation uses inheritance to provide teams with some level of base functio - calls all methods which check data from one submisison ### Writing Custom Checks - - Each check is a method of the `DatValidation2022` class and should take in the data fields it uses as parameters + - Each check is a method of the `DatValidation2025` class and should take in the data fields it uses as parameters - it is recommended to include the `match_key` and `team_number` as parameters of any check since they can be used as identifiers in the error message - Example data check function signature: ``` - def check_for_auto_great_than_6( - self, - match_key: str, - team_number: int, - auto_lower_hub: int, - auto_upper_hub: int, - auto_misses: int, - ) -> None: + def scored_more_than_eight_in_auto( + self, + match_key: str, + team_number: int, + auto_coral: int, + auto_algae: int, + ): ``` - - Teams may then impliment whatever logic they like in the function body + - Teams may then implement whatever logic they like in the function body - To flag an error you must call the `add_error` method which takes two arguments the `error_message` and the `error_type` - The `error_message` is simply a string which describes the error - The `error_type` takes in a value from a predefined enum which is used to categorize the error @@ -89,21 +88,22 @@ Datavalidation uses inheritance to provide teams with some level of base functio ``` - Example call to `add_error` ``` - if balls_shot_in_auto > 6: - self.add_error( - f"In {match_key}, {team_number} UNLIKELY AUTO SHOT COUNT", - error_type=ErrorType.WARNING, + if auto_coral + auto_algae > 8: + self.add_error( + f"In {match_key}, {team_number} was said to have scored {auto_coral} CORAL GAME PIECES AND {auto_algae} ALGAE GAME PIECES IN AUTO WHICH IS IMPOSSIBLE.", + ErrorType.INCORRECT_DATA, + match_key, + team_number, ) ``` - Lastly to run the check the function must be called in either `validate_submission` or `validate_data` and pass in the required data arguments - Example data check function call ``` - def validate_submission(self, submission: Series) -> None: - self.check_for_auto_great_than_6( - match_key=submission["match_key"], - team_number=submission["team_number"], - auto_lower_hub=submission["auto_lower_hub"], - auto_upper_hub=submission["auto_upper_hub"], - auto_misses=submission["auto_misses"], - ) + def validate_submission(self, submission: Series) -> None: + self.scored_more_than_eight_in_auto( + match_key=submission[self.config["match_key"]], + team_number=submission[self.config["team_number"]], + auto_coral=submission[self.config["auto_coral_l1"]] + submission[self.config["auto_coral_l2"]]+submission[self.config["auto_coral_l3"]]+submission[self.config["auto_coral_l4"]], + auto_algae=submission[self.config["auto_processor"]]+submission[self.config["auto_barge"]], + ) ``` \ No newline at end of file diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md index cbc2f0c..bf0f231 100644 --- a/docs/QUICK_START.md +++ b/docs/QUICK_START.md @@ -100,37 +100,60 @@ The Yaml is used to setup our data validation system we provide to check your da ``` # core setup features -year: 2022 -event_code: "iri" -run_with_tba: True +year: 2025 +event_code: "njdd" +run_with_tba: false +path_to_data: "data/2025njdd_match_data.json" +path_to_output: "data/errors.json" # required translation -match_key: "match_key" -team_number: "team_number" +scout_id: "ScoutId" +match_key: "MatchKey" +team_number: "TeamNumber" +alliance: "Alliance" +driver_station": "DriverStation" # optional parameters - if it is needed for a data check and is # not listed, the check will not run -# Rapid React 2022: hyper-specific parameters -auto_lower_hub: "auto_lower_hub" -auto_upper_hub: "auto_upper_hub" -... -taxied: "taxied" -final_climb_type: "final_climb_type" - -# general game parameters -alliance: "alliance" -driver_station: "driver_station" -... -defense_rating: "defense_rating" -counter_defense_rating: "counter_defense_rating" -``` - -The first 3 parameters in the example `year`, `event_code`, `run_with_tba` are used to setup the year specific and general checks to be run. Setting `year` to 2023 will run the 2023 checks if they exist. Setting `event` to iri will cause TBA to grab the iri 2022 schedule and use it for data validation. This will only happen if you choose to use the `run_with_tba` parameter (use only if you have internet connection). - -The rest of the parameters may change yearly but are used to translate the data you collect to the `4099 data val syntax` for that and past year checks. Internally, we use wording like `auto_lower_hub` but if you don't use that same wording, then you can just change your name for it in the yaml file by changing the key. Example ... -``` -taxied: "taxi" +# Reefscape 2025: hyper-specific parameters +auto_starting_position: "StartingPosition" +auto_leave: "AutoLeave" +auto_scoring_side: "ScoringSide" +auto_coral_l1: "AutoCoralL1" +auto_coral_l2: "AutoCoralL2" +auto_coral_l3: "AutoCoralL3" +auto_coral_l4: "AutoCoralL4" +auto_barge: "AutoBarge" +auto_processor: "AutoProcessor" +auto_centerline: "AutoCenterline" +teleop_coral_l1: "TeleopCoralL1" +teleop_coral_l2: "TeleopCoralL2" +teleop_coral_l3: "TeleopCoralL3" +teleop_coral_l4: "TeleopCoralL4" +teleop_algae_barge: "TeleopAlgaeBarge" +teleop_algae_processor: "TeleopAlgaeProcessor" +endgame_parked: "Parked" +endgame_climb_status: "ClimbStatus" +endgame_climb_speed: "ClimbSpeed" +disabled: "Disabled" +stability_rating: "StabilityRating" +robot_style_type: "RobotStyleType" +driver_rating: "DriverRating" +intake_defense_rating: "IntakeDefenseRating" + +# parameters for notes +auto_notes: "AutoNotes" +teleop_notes: "TeleopNotes" +endgame_notes: "EndgameNotes" +rating_notes: "RatingNotes" +``` + +The first 3 parameters in the example `year`, `event_code`, `run_with_tba` are used to setup the year specific and general checks to be run. Setting `year` to 2026 will run the 2026 checks if they exist. Setting `event` to njdd will cause TBA to grab the njdd 2025 schedule and use it for data validation. This will only happen if you choose to use the `run_with_tba` parameter (use only if you have internet connection). + +The rest of the parameters may change yearly but are used to translate the data you collect to the `4099 data val syntax` for that and past year checks. Internally, we use wording like `AutoCoralL1` but if you don't use that same wording, then you can just change your name for it in the yaml file by changing the key. Example ... +``` +endgame_parked: "Parked" ``` The values used in the value pair should be the same values in your `data_labels` in your `config.json`. @@ -188,7 +211,7 @@ src/config/structure.json "type": "GenericTextInput", "text": "Scout Name", "placeholder": [ - "Pranav" + "Nathan" ], "id": "scoutid" }, @@ -235,9 +258,9 @@ For each page you have 4 parts. `name`, `description`, `components`, `export`. - `DropdownTextInput` is used for selection an option and providing a text input inline. This could be used for selecting your match type by setting your options as qm, qf, sf, f and your placeholder as match number. Can take placeholders (1) and options (many) - `GenericTextArea` is used for getting inputs in a paragraph form. Similar to text area in google forms. Can take a placeholder (only 1) but no options - `GenericTextInput` is used for getting inputs in a single line form. Similar to text input in google forms. Can take a placeholder (only 1) but no options - - `IncrementNumberInput` is used to get a number and add or subtract to it. It can be used in Rapid React for getting the ball count. It can take a placeholder for the initial value but no options. + - `IncrementNumberInput` is used to get a number and add or subtract to it. It can be used in Reefscape for getting the Algae count. It can take a placeholder for the initial value but no options. - `SliderInput` is used to get a value on a regular html slider from values a to b. The values are set via two options. Options are used and not placeholders - - `GenericCheckboxSelect` is used for getting multiple values selected. Checkbox like google forms. Can be used for zones in 2022. Takes options in a list and no placeholders + - `GenericCheckboxSelect` is used for getting multiple values selected. Checkbox like google forms. Can be used for climb status. Takes options in a list and no placeholders - `GenericDropdownSelect` is a dropdown which can be used to select one of many options in a list. Options can be given in a list and no placeholders taken. - `GenericRadioSelect` are for selecting an option in a list like the dropdown select but in the ui format of a radio which takes a single value. Takes a list of options and no placeholders - `GenericToggle` is a phone setting-like toggle used for getting a `True` or `False` value from the user. Takes no placeholders or options. diff --git a/docs/WHAT_IS_FALCONSCOUT.md b/docs/WHAT_IS_FALCONSCOUT.md index b646a2e..198beef 100644 --- a/docs/WHAT_IS_FALCONSCOUT.md +++ b/docs/WHAT_IS_FALCONSCOUT.md @@ -26,13 +26,13 @@ The JSON file format is ``` [ { - "scout_id": "Pranav", + "scout_id": "Ryan", ... "team_num": 4099 }, ... { - "scout_id": "Zac", + "scout_id": "Nathan", ... "team_num": 4099 }, From 8500bf71feda8ac0abda5ce81e96f38084c44b22 Mon Sep 17 00:00:00 2001 From: Sammy Date: Sun, 30 Nov 2025 21:00:57 -0500 Subject: [PATCH 2/2] will properly update documentation --- docs/QUICK_START.md | 72 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 59 insertions(+), 13 deletions(-) diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md index bf0f231..9957eec 100644 --- a/docs/QUICK_START.md +++ b/docs/QUICK_START.md @@ -65,21 +65,67 @@ You have two parts to the JSON (`data_config`, `repo_config`) ``` { "data_config": { - "delimiter": ",", - "data_labels": [ - "scout_id", - "match_key", - ... - "teleop_notes", - "misc_notes" + "delimiter": "|", + "quantitative_data_labels": [ + "ScoutId", + "MatchKey", + "Alliance", + "DriverStation", + "TeamNumber", + "StartingPosition", + "AutoLeave", + "ScoringSide", + "AutoCoralL1", + "AutoCoralL2", + "AutoCoralL3", + "AutoCoralL4", + "AutoCoralMisses", + "AutoBarge", + "AutoProcessor", + "AutoNotes", + "TeleopCoralL1", + "TeleopCoralL2", + "TeleopCoralL3", + "TeleopCoralL4", + "TeleopCoralMisses", + "TeleopAlgaeBarge", + "TeleopAlgaeProcessor", + "TeleopAlgaeRemoval", + "TeleopNotes", + "Parked", + "ClimbStatus", + "ClimbSpeed", + "EndgameNotes", + "Disabled", + "StabilityRating", + "RobotStyleType", + "DriverRating", + "IntakeSpeed", + "DefenseRating", + "IntakeDefenseRating", + "RatingNotes" ], - "json_file": "./data/2022iri_match_data.json", - "csv_file": "./data/2022iri_match_data.csv" + "qualitative_data_labels": [ + "ScoutId", + "MatchKey", + "Alliance", + "DriverStation", + "TeamNumber", + "AutoDrivingSkills", + "AutoGeneralNotes", + "TeleopIntakeLocation", + "TeleopGeneralNotes", + "ClimbAlignmentSpeed", + "EndgameGeneralNotes" + ], + "json_file": "./data/2025njdd_match_data.json", + "qualitative_json_file": "./data/2025njdd_qualitative_data.json", + "error_json": "./data/errors.json" }, "repo_config": { - "repo": "team4099/falcontrack", - "update_csv": "data.csv", - "update_json": "data.json" + "repo": "team4099/ScoutingAppData", + "update_json": "2025njdd_match_data.json", + "update_qualitative_json": "2025njdd_qualitative_data.json" } } ``` @@ -96,7 +142,7 @@ In `repo config`, you have 3 parameters. - `update_json` is the file path of the json file on the repository that will be updated when github is synced **YAML Setup** -The Yaml is used to setup our data validation system we provide to check your data using code we've written to identify possible errors like scouting the same robot twice, not scouting, high error data, missing data values, and more. We write a base validation class and a year specific one and plan to release a validation class for 2023. +The Yaml is used to setup our data validation system we provide to check your data using code we've written to identify possible errors like scouting the same robot twice, not scouting, high error data, missing data values, and more. We write a base validation class and a year specific one and plan to release a validation class for 2026. ``` # core setup features