Surveys - Snailz Docs

Skip to content

# Surveys

Generate random surveys on grids.

## `Survey`

Bases: `BaseModel`

A single survey.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`ident` | `str` | survey identifier | required
`size` | `int` | survey size | required
`start_date` | `date` | Start date for specimen collection | `datetime.date(2024, 3, 1)`
`end_date` | `date` | End date for specimen collection | `datetime.date(2024, 4, 30)`
`cells` | `Grid[int]` | survey cells | `<dynamic>`

Source code in `src/snailz/surveys.py`

    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    class Survey(BaseModel):
        """A single survey."""

        ident: str = Field(description="survey identifier")
        size: int = Field(description="survey size")
        start_date: date = Field(
            default=date.fromisoformat("2024-03-01"),
            description="Start date for specimen collection",
        )
        end_date: date = Field(
            default=date.fromisoformat("2024-04-30"),
            description="End date for specimen collection",
        )
        cells: Grid[int] = Field(
            default_factory=lambda data: model.survey_initialize_grid(data["size"]),
            description="survey cells",
        )

        model_config = {"extra": "forbid"}

        def max_pollution(self) -> float:
            """Maximum pollution value in this survey."""
            assert self.cells is not None  # for type checking
            result = self.cells[0, 0]
            for x in range(self.size):
                for y in range(self.size):
                    result = max(result, self.cells[x, y])
            return result

        def to_csv(self) -> str:
            """Create a CSV representation of a single survey.

            Returns:
                A CSV-formatted string with survey cells.
            """
            assert isinstance(self.cells, Grid)
            output = io.StringIO()
            for y in range(self.size - 1, -1, -1):
                temp = [f"{self.cells[x, y]}" for x in range(self.size)]
                print(",".join(temp), file=output)
            return output.getvalue()

### `max_pollution()`

Maximum pollution value in this survey.

Source code in `src/snailz/surveys.py`

    34
    35
    36
    37
    38
    39
    40
    41
    def max_pollution(self) -> float:
        """Maximum pollution value in this survey."""
        assert self.cells is not None  # for type checking
        result = self.cells[0, 0]
        for x in range(self.size):
            for y in range(self.size):
                result = max(result, self.cells[x, y])
        return result

### `to_csv()`

Create a CSV representation of a single survey.

Returns:

Type | Description
--- | ---
`str` | A CSV-formatted string with survey cells.

Source code in `src/snailz/surveys.py`

    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    def to_csv(self) -> str:
        """Create a CSV representation of a single survey.

        Returns:
            A CSV-formatted string with survey cells.
        """
        assert isinstance(self.cells, Grid)
        output = io.StringIO()
        for y in range(self.size - 1, -1, -1):
            temp = [f"{self.cells[x, y]}" for x in range(self.size)]
            print(",".join(temp), file=output)
        return output.getvalue()

## `AllSurveys`

Bases: `BaseModel`

A set of generated surveys.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`items` | `list[Survey]` | all surveys | required

Source code in `src/snailz/surveys.py`

    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    class AllSurveys(BaseModel):
        """A set of generated surveys."""

        items: list[Survey] = Field(description="all surveys")

        model_config = {"extra": "forbid"}

        def max_pollution(self) -> float:
            """Maximum cell value of all surveys in this set."""
            return max(survey.max_pollution() for survey in self.items)

        @staticmethod
        def generate(params: SurveyParams) -> "AllSurveys":
            """Generate random surveys.

            Parameters:
                params: Data generation parameters.

            Returns:
                Data model including all surveys.
            """

            gen = utils.unique_id("survey", _survey_id_generator)
            current_date = params.start_date
            items = []
            for _ in range(params.number):
                next_date = current_date + model.days_to_next_survey(params)
                items.append(
                    Survey(
                        ident=next(gen),
                        size=params.size,
                        start_date=current_date,
                        end_date=next_date,
                    )
                )
                current_date = next_date + timedelta(days=1)

            return AllSurveys(items=items)

### `max_pollution()`

Maximum cell value of all surveys in this set.

Source code in `src/snailz/surveys.py`

    64
    65
    66
    def max_pollution(self) -> float:
        """Maximum cell value of all surveys in this set."""
        return max(survey.max_pollution() for survey in self.items)

### `generate(params)` `staticmethod`

Generate random surveys.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`params` | `SurveyParams` | Data generation parameters. | required

Returns:

Type | Description
--- | ---
`AllSurveys` | Data model including all surveys.

Source code in `src/snailz/surveys.py`

    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    @staticmethod
    def generate(params: SurveyParams) -> "AllSurveys":
        """Generate random surveys.

        Parameters:
            params: Data generation parameters.

        Returns:
            Data model including all surveys.
        """

        gen = utils.unique_id("survey", _survey_id_generator)
        current_date = params.start_date
        items = []
        for _ in range(params.number):
            next_date = current_date + model.days_to_next_survey(params)
            items.append(
                Survey(
                    ident=next(gen),
                    size=params.size,
                    start_date=current_date,
                    end_date=next_date,
                )
            )
            current_date = next_date + timedelta(days=1)

        return AllSurveys(items=items)

## `_survey_id_generator()`

Generate unique ID for a survey.

Returns:

Type | Description
--- | ---
`str` | Candidate ID 'gNNN'.

Source code in `src/snailz/surveys.py`

     97
     98
     99
    100
    101
    102
    103
    104
    105
    def _survey_id_generator() -> str:
        """Generate unique ID for a survey.

        Returns:
            Candidate ID 'gNNN'.
        """

        num = random.randint(0, 999)
        return f"S{num:03d}"