*! version 1.0.0 25mar2026
help leslie

Title

leslie -- Computes demographic projections, stable analysis,
and summary measures for one-sex, two-sex and multistate populations

Syntax

leslie, period(integer) [options]

Options

srb(real) ratio of boys to girls at birth

male include this option for male-dominant projections

total include this option to project the total population
(females and males combined)

l0(integer) radix of the life table

extraT(numlist) person-years remaining in the extra last open age
group

two if the input data refers to two-sex populations

fert(numlist) expected tfr in the last projection period

baseline(integer) baseline year of the projection

place(string) region, subregion, country or area from which
the final age-specific fertility standard is borrowed

surv(numlist) expected e0 in the last projection
period

sigma(numlist) expected slope of the ultimate survival curve

nmr(string) get net migration rates from an external dataset
specified in parentheses

mig1(string) computes the residual number of net migrants
by age and includes them in the projections

mig2 splits migrants over the projection period

multistate if the input data refers to multistate
populations

nomobility excludes mobility from the projections

stable computes stable-equivalent age structures

summary calculates summary demographic measures

tolerance(real) threshold of stability

keyfitz implements Keyfitz's delta in the calculation of
distance to stability

ygual(integer) young group upper age limit

gropts(string) options for twoway graphs

Description

leslie forward projects populations structured by age, sex, and
other states of interest using matrix models. The program implements the methods
and procedures first introduced by Leslie (1945), and later developed by
Rogers (1966, 1995). The program produces projections for one- or
two-sex populations, with or without net migration, and also performs
multistate projections, with or without considering mobility between
subpopulations. The stable option calculates the age structure of
stable-equivalent populations, and summary computes several demographic
measures characterizing the current population (tfr, nrr, e0, grr, mean age
at death and of the population, intrinsic rates, momentum etc.). The inputs
for one-sex and two-sex projections are:

1) the population aged x to x+n at a base year at time t;

2) the number of person-years (L_x);

3) age-specific fertility rates for women of reproductive age; and

4) a file containing the population in the previous period (t-5),
if the user chooses to include the residual number of net migrants in the
projections.

For multistate projections, the inputs are:

1) the populations aged x to x+n in the initial year;

2) the probability of dying in state i at age x (qi_x);

3) age-specific fertility rates;

4) transition probabilities between states of origin i and destination
j at age x; and

5)	a categorical variable identifying each state i.

An adequate dataset should have variables in this order before being
entered into Stata. For two-sex projections, the first half of the rows must
refer to women (with age-specific fertility rates), and the second half to men.
Female data must be stacked on top of males. For multistate populations,
each subpopulation should be on top of each other, and the last variable in the
dataset should identify their state of occupancy.

Arguments

Main

period(integer) specifies the number of projection
periods. One period is equal to the length of the age groups (n). For
example, if n=5, specifying period(10) will project the population
for 50 years. period( ) is required.

Options

srb(real) represents the ratio of boys over girls at birth.
By default, this scalar is set to 1.05, suitable for female-dominant and
multistate projections.

male include this option for male-dominant projections.

total include this option to project the total population (females
and males combined in a single vector).

l0(integer) denotes the arbitrary radix of the life table. This scalar is
used in one-sex and two-sex population projections to calculate the survival
probability of births in the first age group. By convention, the default
value is 100,000. It should only be altered if the number of entered
person-years lived (L_x) derives from a number of survivors (l_x) with a life
table radix different from 100,000.

extraT(numlist) allows expert users to define an extra value for
the person-years remaining (T) in the last age open age group. Specifying
this option affects the probabilities of survival in the last two age groups in
the last row of the Leslie projection matrix. These values can be defined for
one-sex or two-sex projection models.

two indicates that the input data refers to two-sex populations
and simultaneously projects the future size of the age-specific female and male
populations. It also produces a graph highlighting the age structure of the
first and last projections.

fert(numlist) sets the total fertility rate expected in the last
projection period. This value corresponds to the analyst's expectation of how
many children women will bear in the future and defines the rhythm of fertility
change throughout the projection period.

baseline(integer) specifies the baseline year of the projection.
Use this option with fert() or place() to determine and borrow the
age-specific fertility standard for the final projection period. The standard
is sourced from median variant data in the World Population Prospects
(e.g., United Nations 2024). When used with fert(), it selects the
fertility standard with the closest total fertility rate in the ultimate
projection year. When used with place(), it retrieves the exact
fertility standard of the specified location for the final projection year.

place(string) must be used with baseline(). Specifies the
region, subregion, country, or area from which the final life expectancy
and/or age-specific fertility standard is borrowed.

surv(numlist) sets the life expectancy at birth expected in the last
projection period. For two-sex projection models, the user must consecutively
enter one value for females and one for males. Setting these values defines the
dynamics of convergence between current and future levels of survival.

sigma(numlist) sets alternative values for the slope of the survival
curve expected in the last projection period. This option allows expert users
to investigate the consequences of different survival patterns on future
demographic projections. For two-sex projection models, the user must enter two
expected values: one for females and one for males.

mig1(string) computes the residual number of net migrants by age
from the difference between the observed and projected populations at time
t. A dataset containing a single variable with age-specific populations
at time t-5 must be enclosed in parentheses for the program to calculate
the expected population. This option includes residual migrants in the
projections, assuming movements occur at the beggining of the period.
Example: leslie, p(10) mig1(sweden_1988_female.dta).

mig2 must be used with with the mig1() option to include
half of the migrants at the beginning and half at the end of the projection
interval (Preston el al. 2001, 125).

multistate indicates that the input data refers to multistate
populations and assembles a block matrix to simultaneously project the future
size of age- and state-specific populations. It also produces a graph
highlighting the age structure of the first and last projected populations in
each state.

nomobility produces state-specific projections considering
survival and fertility rates, but zeroing off-diagonal matrices in the
"growth" block-matrix used for multistate projections.

stable displays a graph and a comparative table of current,
stationary and stable-equivalent age structures.

summary calculates demographic measures related to the current
population and its future dynamics. These measures include tfr, nrr, grr,
life expectancy at birth, population momentum, intrinsic rates, mean ages at
death and maternity, Keyfitz's delta, time to reach stability, length of a
generation, total dependency ratio, and others. For multistate populations,
this option additionally calculates conditional state-specific life
expectancies at birth.

tolerance(real) set the tolerance level used to define the
criterion of proximity to the stable equivalent age structure, influencing the
calculation of the number of years to stability. The default value is
1e-6.

keyfitz tells leslie to use Keyfitz's delta to calculate
the number of years to stability in one-sex projection models.

ygual(integer) sets the young group upper age limit in the
calculation of the total age dependency ratio. The default is 14 years
old.

gropts(twoway_options) allows the inclusion of options for
twoway graphs, such as scheme(schemename), nodraw,
saving(filename, ...), and others.

Output

As a minimum, leslie displays a table and a graph of populations
projected by age, sex or occupancy states (multistate option).

In single state projections the program optionally includes the number
of residual net migrants (mig1() and mig2 options). It is also able
to generate stable-equivalent age structures (stable option) and several key
demographic measures (summary option) for one-sex, two-sex, and multistate
populations.

Saved Results

leslie returns projected populations, age-structures, and
summary measures as system matrices under the following names:

Stata matrices

r(proj) The rows represent the lower bounds of the age groups and
the columns show the successive projected one-sex populations. If migrants are
included in the projection (bmigration option), the results are stored in
the same matrix

r(mproj) For a two-sex population (two option), this matrix
returns the future size of the age-specific male population. Projections with
migration are also stored in this matrix

r(fproj) For a two-sex population (two option), this matrix
returns the future size of the age-specific female population. Projections with
migration are also stored in this matrix

r(mproji) Returns a matrix of successive projected
populations by age for each state i equal to 1, 2, 3... if the
multistate option is specified. Projections with the additional option
nomobility are saved under the same name

r(mstablei) This matrix returns stable-equivalent age
structures of the population in state i when options multistate and
stable are specified at the same time

r(stable) This matrix returns stable-equivalent age
structures of one-sex poulations when option stable is included

r(mstable) Stable-equivalent age structures of male populations
when options two and stable are simultaneously specified

r(fstable) Stable-equivalent age structures of female
populations when options two and stable are simultaneously
specified

r(summary) Returns a matrix with 21 measures for one-sex, 16 for
two-sex, and eight for multistate populations if the summary option is
specified

r(summary2) Returns a matrix containing six measures about the
future dynamics of a multistate population. This matrix is generated whenever
the options multistate and summary are invoked simultaneously

r(summary3) Simultaneously invoking the multistate and
summary options generates a matrix with conditional state-specific life
expectancies: the sojourn time in state j given occupancy of state i

Mata matrices

M Is the (block) matrix assembled to project input populations.
For one- and two-sex populations its elements follow the structure of a
conventional Leslie matrix (Leslie 1945). For multistate projections, the matrix
M is structured according to the "multiregional matrix growth operator
model" (Rogers 1995, 117)

T Is a column vector with the age-specific number of person-years
remaining. It also represents life expectancies. It is computed for one- and
two-sex population projection models

Remarks

I developed and tested leslie having in mind the most prevalent
type of demographic data: populations organized into 5-year age groups.
The recommendation is to structure the data in this fashion before entering them
into Stata.

Examples

1. To project the female population for 10 periods, one should type:

. leslie, period(10)

2. To project the male population five periods forward, assuming a
radix for the life table of 150,000:

. leslie, period(5) male l0(150000)

3. To project female and male populations entered at the same time for 15
periods:

. leslie, period(15) two

4. To include residual net migrants in the projections, the user must
specify a file containing the population observed in the previous period. For
example, to include female Swedish migrants in a 10-years projection of the
1993 population, type:

. leslie, period(10) mig1(sweden_1988_female.dta)

5. For multistate projections type:

. leslie, period(10) multistate

6. To request a table and a graph of multistate projections without
mobility but with stability analysis:

. leslie, period(10) multistate nomobility stable

7. To request summary demographic measures for one-sex, two-sex, and
multistate populations projected for 20 periods, respectively type:

. leslie, period(20) summary

. leslie, period(20) two summary

. leslie, period(20) multistate summary

8. To simultaneously project female and male populations assuming that
the total fertility rate and life expectancies at birth in the 20th projection
period will respectively be 2.01 children, 85 years for females, and 80 years
for males, type:

. leslie, two period(20) fert(2.01) surv(85 80)

9. To simultaneously project female and male populations assuming that
the total fertility rate and life expectancies at birth in the 20th projection
period will respectively be 2.01 children, 85 years for females, and 80 years
for males, type:

. leslie, two period(20) fert(2.01) surv(85 80)

References

Indispensable references on matrix models for demographic projections
are:

Leslie, P. H. 1945. On the use of matrices in certain population
mathematics. Biometrika 33(3): 183-212.

Rogers, A. 1966. The multiregional matrix growth operator and the stable
interregional age structure. Demography 3(2): 537-544.

Rogers, A. 1995. Multiregional demography: principles, methods and
extensions. England: John Wiley and Sons Ltd.

Please contact Jerônimo O. Muniz <jeronimo@ufmg.br> to report bugs
and to suggest future improvements.