Parameters - Snailz Docs

Skip to content

# Parameters

Data generation parameters.

## `Parameters` `dataclass`

Store all data generation parameters.

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

     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
     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
     91
     92
     93
     94
     95
     96
     97
     98
     99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    @dataclass
    class Parameters:
        """
        Store all data generation parameters.
        """

        seed: int = 12345
        """Random number generator seed for reproducible data generation."""

        num_grids: int = 1
        """Number of survey grids to create."""

        grid_size: int = 1
        """Width and height of each survey grid in cells."""

        grid_spacing: float = 10.0
        """Size of each grid cell in meters."""

        grid_separation: int = 4
        """Minimum separation between grid origin points as multiple of total grid size."""

        grid_std_dev: float = 0.5
        """Standard deviation of noise applied to grid pollution values."""

        lat0: float = 48.8666632
        """Reference latitude for all grids."""

        lon0: float = -124.1999992
        """Reference longitude for all grids."""

        num_persons: int = 1
        """Number of persons to generate."""

        supervisor_frac: float = 0.3
        """Fraction of persons who are supervisors of other persons."""

        locale: str = "et_EE"
        """Locale for generating personal and family names of persons."""

        num_machines: int = 1
        """Number of machines to generate."""

        ratings_frac: float = 0.5
        """Fraction of (person, machine) pairs to be given ratings."""

        p_certified: float = 0.3
        """Probability that a particular person is certified for a particular machine."""

        num_assays: int = 1
        """Number of soil pollution assays to generate."""

        assay_size: int = 2
        """Number of control or treatment values to include in each assay."""

        assay_certified: float = 3.0
        """How much to narrow standard deviation in assay pollution if operator is certified."""

        genome_length: int = 1
        """Length of species genome in bases."""

        num_loci: int = 1
        """Number of loci in genome at which mutations may occur."""

        p_mutation: float = 0.5
        """Probability of mutation at each locus."""

        num_specimens: int = 1
        """Number of snail specimens to create."""

        mass_beta_0: float = 3.0
        """Fixed mean for log-normal snail mass generation."""

        mass_beta_1: float = 0.5
        """Scaling factor for pollution in mean of log-normal snail mass generation."""

        mass_sigma: float = 0.3
        """Standard deviation in log-normal generation of snail mass."""

        diam_ratio: float = 0.7
        """Mean of ratio of snail diameter to mass."""

        diam_sigma: float = 0.7
        """Standard deviation in snail diameter generation."""

        start_date: date = date(2026, 3, 1)
        """Start date of survey."""

        end_date: date = date(2026, 5, 31)
        """End date of survey."""

        p_date_missing: float = 0.1
        """Probability that specimen collection date is missing."""

        def __post_init__(self):
            """Validate fields."""

            validate(self.num_grids > 0, "require positive number of grids")
            validate(self.grid_size > 0, "require positive grid size")
            validate(self.grid_spacing > 0, "require positive grid spacing")
            validate_lat_lon("parameters", self.lat0, self.lon0)
            validate(self.num_persons > 0, "require positive number of persons")
            validate(
                self.supervisor_frac >= 0.0, "require non-negative supervisor fraction"
            )
            validate(self.locale in AVAILABLE_LOCALES, f"unknown locale {self.locale}")
            validate(self.num_machines > 0, "require positive number of machines")
            validate(0.0 <= self.ratings_frac <= 1.0, "require ratings fraction in [0..1]")
            validate(self.num_assays >= 1, "require at least one assay")
            validate(self.assay_size >= 2, "require assay size at least two")
            validate(self.genome_length > 0, "require positive genome length")
            validate(self.num_loci >= 0, "require non-negative number of loci")
            validate(
                0.0 <= self.p_mutation <= 1.0, "require mutation probability in [0..1]"
            )
            validate(self.num_specimens > 0, "require positive number of specimens")
            validate(
                self.start_date <= self.end_date, "require non-negative survey date range"
            )
            validate(
                0.0 <= self.p_date_missing <= 1.0, "require missing date probability in [0..1]"
            )

        def as_json(self, indent: int = JSON_INDENT) -> str:
            """
            Convert parameters to a JSON string.

            Args:
                indent: Indentation.

            Returns:
                JSON string representation of persistable fields.
            """
            return json.dumps(self.__dict__, indent=indent, default=_serialize_json)

### `seed = 12345` `class-attribute` `instance-attribute`

Random number generator seed for reproducible data generation.

### `num_grids = 1` `class-attribute` `instance-attribute`

Number of survey grids to create.

### `grid_size = 1` `class-attribute` `instance-attribute`

Width and height of each survey grid in cells.

### `grid_spacing = 10.0` `class-attribute` `instance-attribute`

Size of each grid cell in meters.

### `grid_separation = 4` `class-attribute` `instance-attribute`

Minimum separation between grid origin points as multiple of total grid size.

### `grid_std_dev = 0.5` `class-attribute` `instance-attribute`

Standard deviation of noise applied to grid pollution values.

### `lat0 = 48.8666632` `class-attribute` `instance-attribute`

Reference latitude for all grids.

### `lon0 = -124.1999992` `class-attribute` `instance-attribute`

Reference longitude for all grids.

### `num_persons = 1` `class-attribute` `instance-attribute`

Number of persons to generate.

### `supervisor_frac = 0.3` `class-attribute` `instance-attribute`

Fraction of persons who are supervisors of other persons.

### `locale = 'et_EE'` `class-attribute` `instance-attribute`

Locale for generating personal and family names of persons.

### `num_machines = 1` `class-attribute` `instance-attribute`

Number of machines to generate.

### `ratings_frac = 0.5` `class-attribute` `instance-attribute`

Fraction of (person, machine) pairs to be given ratings.

### `p_certified = 0.3` `class-attribute` `instance-attribute`

Probability that a particular person is certified for a particular machine.

### `num_assays = 1` `class-attribute` `instance-attribute`

Number of soil pollution assays to generate.

### `assay_size = 2` `class-attribute` `instance-attribute`

Number of control or treatment values to include in each assay.

### `assay_certified = 3.0` `class-attribute` `instance-attribute`

How much to narrow standard deviation in assay pollution if operator is certified.

### `genome_length = 1` `class-attribute` `instance-attribute`

Length of species genome in bases.

### `num_loci = 1` `class-attribute` `instance-attribute`

Number of loci in genome at which mutations may occur.

### `p_mutation = 0.5` `class-attribute` `instance-attribute`

Probability of mutation at each locus.

### `num_specimens = 1` `class-attribute` `instance-attribute`

Number of snail specimens to create.

### `mass_beta_0 = 3.0` `class-attribute` `instance-attribute`

Fixed mean for log-normal snail mass generation.

### `mass_beta_1 = 0.5` `class-attribute` `instance-attribute`

Scaling factor for pollution in mean of log-normal snail mass generation.

### `mass_sigma = 0.3` `class-attribute` `instance-attribute`

Standard deviation in log-normal generation of snail mass.

### `diam_ratio = 0.7` `class-attribute` `instance-attribute`

Mean of ratio of snail diameter to mass.

### `diam_sigma = 0.7` `class-attribute` `instance-attribute`

Standard deviation in snail diameter generation.

### `start_date = date(2026, 3, 1)` `class-attribute` `instance-attribute`

Start date of survey.

### `end_date = date(2026, 5, 31)` `class-attribute` `instance-attribute`

End date of survey.

### `p_date_missing = 0.1` `class-attribute` `instance-attribute`

Probability that specimen collection date is missing.

### `__post_init__()`

Validate fields.

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

    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    def __post_init__(self):
        """Validate fields."""

        validate(self.num_grids > 0, "require positive number of grids")
        validate(self.grid_size > 0, "require positive grid size")
        validate(self.grid_spacing > 0, "require positive grid spacing")
        validate_lat_lon("parameters", self.lat0, self.lon0)
        validate(self.num_persons > 0, "require positive number of persons")
        validate(
            self.supervisor_frac >= 0.0, "require non-negative supervisor fraction"
        )
        validate(self.locale in AVAILABLE_LOCALES, f"unknown locale {self.locale}")
        validate(self.num_machines > 0, "require positive number of machines")
        validate(0.0 <= self.ratings_frac <= 1.0, "require ratings fraction in [0..1]")
        validate(self.num_assays >= 1, "require at least one assay")
        validate(self.assay_size >= 2, "require assay size at least two")
        validate(self.genome_length > 0, "require positive genome length")
        validate(self.num_loci >= 0, "require non-negative number of loci")
        validate(
            0.0 <= self.p_mutation <= 1.0, "require mutation probability in [0..1]"
        )
        validate(self.num_specimens > 0, "require positive number of specimens")
        validate(
            self.start_date <= self.end_date, "require non-negative survey date range"
        )
        validate(
            0.0 <= self.p_date_missing <= 1.0, "require missing date probability in [0..1]"
        )

### `as_json(indent=JSON_INDENT)`

Convert parameters to a JSON string.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`indent` | `int` | Indentation. | `JSON_INDENT`

Returns:

Type | Description
--- | ---
`str` | JSON string representation of persistable fields.

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

    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    def as_json(self, indent: int = JSON_INDENT) -> str:
        """
        Convert parameters to a JSON string.

        Args:
            indent: Indentation.

        Returns:
            JSON string representation of persistable fields.
        """
        return json.dumps(self.__dict__, indent=indent, default=_serialize_json)