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
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
        return self.cells.max()

    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
def max_pollution(self) -> float:
    """Maximum pollution value in this survey."""
    assert self.cells is not None  # for type checking
    return self.cells.max()

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
39
40
41
42
43
44
45
46
47
48
49
50
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
53
54
55
56
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
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
60
61
62
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
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
@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
 93
 94
 95
 96
 97
 98
 99
100
101
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}"