Repository navigation
Initialisation Workflows
This section is intended as a practical guide for configuring initialisation in OSMOSE 4.4. The previous sections described the conceptual logic of the main methods and the way the current implementation operates. The present section focuses on user decisions: how to choose an initialisation method, what parameters must be supplied, what they mean, and what checks should be performed before running a simulation.
The most important practical point is that OSMOSE 4.4 supports more than one representation of the initial state. In the reconstructed population-level initialisation, the direct initial state is a population-level parameter block that the OSMOSE core simulator later expands into schools. In the direct school-level initialisation, the direct initial state is already a school-by-school file. In egg seeding initialisation, the early population emerges indirectly through seeded reproduction. Because these methods operate differently, users should first decide which workflow is appropriate for their application before assembling the corresponding parameter set.
In most ordinary modelling applications, reconstructed population-level initialisation should be the preferred starting point. It provides a practical compromise between explicitness and usability, because it allows the initial state to be reconstructed from standard species parameterisation together with biomass and fishery information, without requiring a hand-built school-level file. It is especially appropriate when the user has a conventional OSMOSE configuration with growth, maturity, fecundity, and length–weight parameters already defined, and when at least some information on biomass, yield, or catch-at-length is available.
Direct school-level initialisation should be preferred when the user already has an explicit school-level state and wishes to reuse it directly. Typical examples include restart workflows, coupling applications, or cases where a prepared school-level file is available from a previous OSMOSE run or from an external process. This route is the most explicit, but it also requires the most detailed input.
Egg seeding initialisation should be reserved for cases where an indirect, reproduction-based route is acceptable or desirable. It should not normally be the first choice when an explicit or inspectable initial state is required.
The choice can therefore be summarised as follows:
- use reconstructed population-level initialisation for most general applications, specially for trasient simulation experiments and hindcast applications;
- use direct school-level initialisation when an explicit school file is already available or required;
- use egg seeding initialisation only when this feature is intentionally needed.
The data-rich workflow corresponds to the original design context of reconstructed population-level initialisation. In this case, the user supplies, for each focal species, an observed biomass series, a biomass cutoff size, a yield series, and catch-at-length information, together with the standard species biological parameterisation. This is the recommended workflow whenever such information is available.
In practice, the user enables reconstructed population-level initialisation, provides the data-layer inputs, checks that growth, maturity, reproduction, and length–weight parameters are already defined in the regular OSMOSE parameterisation, and then generates the population.initialization.* block. This is the most informative workflow because the reconstruction is constrained by both abundance-related and fishery-related information.
When only part of the intended data set is available, reconstructed population-level initialisation can still be used, but the reconstruction will depend more strongly on the assumed biological and selectivity settings. A common example is a situation where biomass and yield are available but catch-at-length is not. In that case, the user must provide a selectivity function through the corresponding selectivity parameters, because selectivity can no longer be inferred empirically from observed size composition.
This workflow remains perfectly valid, but the resulting initial state should be inspected carefully, especially the size structure, the implied fishing pattern, and the estimated larval mortality.
In some cases, the user may not have an observed biomass series and may instead provide only an approximate biomass guess. This corresponds to one of the later extensions added to the original reconstructed population-level method to support more data-poor situations. The resulting configuration is useful, but it is less strongly constrained than the intended data-rich setup.
This workflow is particularly relevant for species that are included as focal species but for which formal biomass estimates are not available. In such cases, the biomass guess should be interpreted as a practical approximation used to obtain a coherent starting state rather than as a strict observation target. Is strongly recommended that this biomass guess estimate is calibrated in a later stage of the model development.
When a school-level initial-condition file is already available, the simplest and most explicit workflow is to provide that file directly through population.initialization.file. This avoids the need to reconstruct a class-based population block and is the natural route for restart situations.
This workflow is also the most suitable one when exact school-level information, including spatial position, is important to the user. By contrast, reconstructed population-level initialisation is primarily designed to recover demographic structure and biomass distribution rather than a full school-level spatial state.
A further possibility is to provide the population.initialization.* parameters manually. This is effectively a manual version of population-level initialisation, in which the user constructs the parameter block directly without using the reconstruction procedure. It can be useful when the user already has a suitable class-based description of the initial state and wants direct control over the population-level input.
This route is flexible, but it also places responsibility on the user to ensure that the parameter block is internally consistent, especially with respect to class definitions, vector lengths, biomass allocation, and school counts. This route is notably useful in a data-rich setup and only for species that are central for the objectives of the modelling work. As the reconstructed population-level initialisation operates at the species-level, this manual approach can be combined with the automated population-level initialisation.
The parameters involved in initialisation can be organised into six main groups: method-selection flags, seeding parameters, direct school-level initialisation parameters, data-layer parameters for reconstructed population-level initialisation, the resulting population.initialization.* block, and the biological and selectivity parameters required indirectly by the reconstruction procedure.
The main method-selection flag for reconstructed population-level initialisation is:
population.initialization.relativebiomass.enabled = TRUE
Despite the historical name of the parameter, this flag activates the reconstructed population-level route documented in Section 4, and it might be changed in a future release. In practice, it indicates that OSMOSE should use the population-level parameterised representation rather than relying exclusively on seeding or on a direct school-level file.
Users should treat this parameter name as part of the OSMOSE 4.4 implementation rather than as the conceptual name of the method.
Egg seeding is controlled principally through:
population.seeding.year.max
population.seeding.biomass.spX
population.seeding.abundance.spX
The parameter population.seeding.year.max gives the maximum duration of seeding in years. It is converted internally into model time steps.
The parameters population.seeding.biomass.spX and population.seeding.abundance.spX provide the species-specific seeding quantities. Which one is effectively used depends on reproduction mode: oviparous species use biomass-based seeding, whereas viviparous species use abundance-based seeding.
In practical terms, users should ensure that the chosen seeding quantity is consistent with the species reproduction mode and with the intended use of seeding, whether as a bootstrap mechanism or as a collapse safeguard.
Direct school-level initialisation uses:
population.initialization.file
This parameter points to a restart-like netCDF file containing one record per school. The file is the initial condition itself and must therefore already contain the school-level state in a valid format.
The data layer for reconstructed population-level initialisation includes parameters that provide the information needed to reconstruct the class-based population structure. These include, among others:
observed.biomass.file.spX
observed.biomass.ndtPerYear.spX
observed.biomass.cutoff.size.spX
observed.biomass.guess.spX
fisheries.catchatlength.file.spX
fisheries.catchatlength.ndtPerYear.spX
fisheries.yield.file.spX
fisheries.yield.ndtPerYear.spX
species.egg.stage.duration.spX
The biomass file and yield file provide the main abundance and fishery targets used in the reconstruction. The biomass cutoff size defines the lower size limit above which reconstructed biomass is compared with the biomass observation. The biomass guess provides a fallback approximation when a full biomass time series is unavailable. The catch-at-length file provides size-composition information that can be used to infer selectivity empirically. Egg-stage duration enters the mortality calculation used internally by the reconstruction method.
Users should remember that these parameters belong to the data layer. They are used to generate the initial condition, but they are not the initial condition itself.
A major practical advantage of reconstructed population-level initialisation is that most of the biological parameters it uses are already part of the regular OSMOSE species configuration. These are not usually redefined specifically for initialisation. Instead, the method reuses them. Relevant examples include growth parameters, length–weight parameters, maturity descriptors, reproductive parameters, lifespan, and sex ratio.
From a user perspective, this means that the consistency of initialisation depends strongly on the consistency of the ordinary species parameterisation. Initialisation problems are therefore often not caused by the initialisation flags themselves, but by unrealistic or incompatible biological settings elsewhere in the configuration.
When catch-at-length is unavailable, users must provide selectivity parameters so that fishing mortality can be distributed across sizes consistently with an assumed selectivity curve. Depending on the selected form, relevant parameters may include:
fisheries.selectivity.type.spX
fisheries.selectivity.l50.spX
fisheries.selectivity.l75.spX
fisheries.selectivity.l25.spX
fisheries.selectivity.l0.spX
fisheries.selectivity.l1.spX
fisheries.selectivity.plateau.spX
fisheries.selectivity.breaks.spX
fisheries.selectivity.values.spX
These parameters are only needed when empirical catch-at-length data are not available or not used. Their interpretation depends on the selectivity type, so users should check carefully that the selected functional form matches the information they actually have.
The direct population-level initialisation block used by the OSMOSE core simulator consists mainly of:
population.initialization.biomass.spX
population.initialization.relativebiomass.spX
population.initialization.size.spX
population.initialization.age.spX
population.initialization.tl.spX
population.initialization.nschool.spX
The meaning of these parameters is as follows.
population.initialization.biomass.spX gives the total initial biomass of the species in tonnes.
population.initialization.relativebiomass.spX gives the relative biomass allocation among the initial classes.
population.initialization.size.spX gives the class boundaries in centimetres. This is a critical point: the values define class limits, not class centres. A vector of length (N+1) defines (N) size classes.
population.initialization.age.spX gives the representative age in years associated with each class.
population.initialization.tl.spX gives the class-level trophic level assigned at initialisation.
population.initialization.nschool.spX gives the number of schools to be created in each class.
Depending on the configuration, the generated initialisation block may also include a larval mortality-related parameter such as:
mortality.additional.larva.rate.spX
or
initialization.additional.larva.rate.spX
Users should therefore inspect the full generated block rather than assuming that only the six core vectors will be present.
A recurring source of difficulty in OSMOSE initialisation is that many parameters are technically valid but conceptually misinterpreted. For that reason, it is useful to summarise the most important expected units and formats.
Biomass quantities such as population.initialization.biomass.spX and population.seeding.biomass.spX are expressed in tonnes. School-level weight in direct school-level files is expressed in grams. Length quantities are expressed in centimetres. Ages in population-level initialisation are expressed in years and later converted internally by the OSMOSE core simulator into time-step units.
Vectors defining class-level population structure must have consistent lengths. For a given species, relativebiomass, age, tl, and nschool must all have the same number of values, and that number must match the number of classes implied by the size vector. Since the size vector defines boundaries, its length must be one greater than the number of classes.
For time-series inputs, users must ensure that the associated ndtPerYear parameters correspond to the actual temporal resolution of the file. This is particularly important for biomass, yield, and catch-at-length inputs. An incorrect time resolution will not simply rescale the input; it can alter the interpretation of the data by the reconstruction procedure.
This is probably the most common source of misunderstanding. The data layer consists of observational inputs and auxiliary parameters used to reconstruct the initial state. The initialisation layer consists of the population.initialization.* parameters that actually define the direct population-level input used by the OSMOSE core simulator. The two should never be treated as interchangeable.
Users often assume that the size vector gives representative class sizes. In fact, it gives class boundaries. This distinction is crucial, because the simulator draws school lengths within these intervals. An incorrect interpretation of the size vector will therefore affect the realised school structure.
Population-level vectors must be mutually consistent. If relativebiomass, age, tl, and nschool do not all match the number of classes defined by the size vector, the initialisation block is invalid. Users who provide population-level parameters manually should check this systematically.
Ages in the population-level parameter block are supplied in years, whereas the simulator uses internal time-step units. Time-series inputs also depend on the correct ndtPerYear specification. Confusion between years and time steps is therefore a frequent source of subtle errors.
The biomass cutoff size is not a biological maturity threshold and not a population truncation threshold. It is part of the observation model used during reconstruction: it determines which part of the reconstructed biomass is compared with the biomass index. An unrealistic cutoff may therefore distort the fit even if all other settings are correct.
Very low or otherwise implausible larval mortality estimates should not simply be accepted as numerical output. They often indicate inconsistency among fecundity, maturity, growth, biomass, or yield inputs. Users should treat them as a diagnostic signal and re-examine the biological parameterisation.
Reconstructed population-level initialisation can be used in data-poor situations, but reduced-input setups necessarily place more weight on assumptions. Users should be especially cautious when relying on biomass guesses, assumed selectivity, or sparse fishery information. Such workflows are useful, but they do not constrain the reconstruction in the same way as the intended data-rich setup.
Before running OSMOSE with a new initialisation setup, users should verify at least the following points.
First, confirm that the intended method is actually selected and that no incompatible method-specific parameters are being mixed unintentionally.
Second, if reconstructed population-level initialisation is used, inspect the generated population.initialization.* block directly. Check that total biomass values are plausible, that the relative biomass vectors sum to approximately one, that class boundaries are sensible, and that the age and school-count vectors have consistent lengths.
Third, compare reconstructed biomass and yield with the supplied targets whenever those targets exist. The purpose of the reconstruction is not to reproduce every input perfectly, but a large mismatch should be investigated before the initial state is accepted.
Fourth, inspect larval mortality estimates and the resulting demographic structure for plausibility. Extreme or incoherent values often indicate a deeper inconsistency in the life-history settings.
Fifth, when using direct school-level initialisation, verify that the school-level file contains all required variables and that units are consistent with OSMOSE expectations.
Finally, when using egg seeding, ensure that the seeding quantity and duration are consistent with the intended role of seeding. A value intended only as a minimal safeguard should not accidentally dominate early population dynamics, while a value intended to bootstrap a missing population should not be so small that ordinary reproduction never becomes established.
For most applications, the best practice is to adopt reconstructed population-level initialisation as the default route and to use the ordinary OSMOSE species parameterisation as the biological foundation of the reconstruction. This is the workflow for which the module is most coherent and most informative.
Whenever possible, users should favour the data-rich form of the reconstruction, with biomass, yield, and catch-at-length information all supplied at the appropriate temporal resolution. Reduced-data workflows remain valuable, but they should be treated as practical approximations rather than as equally constrained alternatives.
Users should document clearly whether they are working at the data-layer level, the population-level initialisation level, or the school-level representation level. Much confusion in practice arises from moving between these representations without stating which one is being inspected or modified.
When direct school-level initialisation is used, users should archive the associated file carefully, because it is the initial condition itself. When reconstructed population-level initialisation is used, users should archive both the data-layer inputs and the generated population.initialization.* block. This is important for reproducibility, because the generated block is the actual initial state used by the simulator, while the data-layer inputs explain how that state was obtained.
Finally, users should regard egg seeding as a complementary method rather than as the default general-purpose route. It remains useful in some applications, especially when a data-free or anti-collapse mechanism is desired, but it offers much less direct control over the resulting initial state than the two explicit representations documented in this report.
In summary, good initialisation practice in OSMOSE 4.4 depends on two linked principles: choose the representation that matches the available information, and inspect the resulting initial state explicitly before accepting it as the starting point of a simulation.