Module simuPOP.sampling
This module provides classes and functions that could be used to draw samples
from a simuPOP population. These functions accept a list of parameters such
as subPops ((virtual) subpopulations from which samples will be drawn) and
numOfSamples (number of samples to draw) and return a list of populations. Both
independent individuals and dependent individuals (Pedigrees) are supported.
Independent individuals could be drawn from any Population. pedigree
information is not necessary and is usually ignored. Unique IDs are not needed
either although such IDs could help you identify samples in the parent
Population.
Pedigrees could be drawn from multi-generational populations or age-structured
populations. All individuals are required to have a unique ID (usually tracked
by operator IdTagger and are stored in information field ind_id).
Parents of individuals are usually tracked by operator PedigreeTagger and
are stored in information fields father_id and mother_id. If parental
information is tracked using operator ParentsTagger and information fields
father_idx and mother_idx, a function sampling.indexToID can be
used to convert index based pedigree to ID based Pedigree. Note that
ParentsTagger can not be used to track Pedigrees in age-structured
populations because they require parents of each individual resides in a
parental generation.
All sampling functions support virtual subpopulations through parameter
subPops, although sample size specification might vary. This feature
allows you to draw samples with specified properties. For example, you
could select only female individuals for cases of a female-only disease,
or select individuals within certain age-range. If you specify a list
of (virtual) subpopulations, you are usually allowed to draw certain
number of individuals from each subpopulation.
class BaseSampler
-
class simuPOP.sampling.BaseSampler
A sampler extracts individuals from a simuPOP population and return them
as separate populations. This base class defines the common interface of
all sampling classes, including how samples prepared and returned.
-
BaseSampler(subPops=ALL_AVAIL)
- Create a sampler with parameter subPops, which will be used
to prepare population for sampling. subPops should be a list of
(virtual) subpopulations from which samples are drawn. The default
value is ALL_AVAIL, which means all available subpopulations of a
Population.
-
drawSample(pop)
- Draw and return a sample.
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
prepareSample(pop, rearrange)
- Prepare passed population object for sampling according to parameter
subPops. If samples are drawn from the whole population, a
Population will be trimmed if only selected (virtual) subpopulations
are used. If samples are drawn separately from specified subpopulations,
Population pop will be rearranged (if rearrange==True) so that
each subpoulation corresponds to one element in parameter subPops.
class RandomSampler
-
class simuPOP.sampling.RandomSampler
A sampler that draws individuals randomly.
-
RandomSampler(sizes, subPops=ALL_AVAIL)
- Creates a random sampler with specified number of individuals.
-
drawSample(input_pop)
- Draw a random sample from passed population.
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
prepareSample(pop, rearrange)
- Prepare passed population object for sampling according to parameter
subPops. If samples are drawn from the whole population, a
Population will be trimmed if only selected (virtual) subpopulations
are used. If samples are drawn separately from specified subpopulations,
Population pop will be rearranged (if rearrange==True) so that
each subpoulation corresponds to one element in parameter subPops.
Function drawRandomSample
-
simuPOP.sampling.drawRandomSample(pop, sizes, subPops=ALL_AVAIL)
- Draw sizes random individuals from a population. If a single sizes
is given, individuals are drawn randomly from the whole population or
from specified (virtual) subpopulations (parameter subPops). Otherwise,
a list of numbers should be used to specify number of samples from each
subpopulation, which can be all subpopulations if subPops=ALL_AVAIL
(default), or from each of the specified (virtual) subpopulations. This
function returns a population with all extracted individuals.
Function drawRandomSamples
-
simuPOP.sampling.drawRandomSamples(pop, sizes, numOfSamples=1, subPops=ALL_AVAIL)
- Draw numOfSamples random samples from a population and return a list of
populations. Please refer to function drawRandomSample for more details
about parameters sizes and subPops.
class CaseControlSampler
-
class simuPOP.sampling.CaseControlSampler
A sampler that draws affected and unaffected individuals randomly.
-
CaseControlSampler(cases, controls, subPops=ALL_AVAIL)
- Ceates a case-control sampler with specified number of cases
and controls.
-
drawSample(input_pop)
- Draw a case control sample
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
prepareSample(input_pop)
- Find out indexes all affected and unaffected individuales.
Function drawCaseControlSample
-
simuPOP.sampling.drawCaseControlSample(pop, cases, controls, subPops=ALL_AVAIL)
- Draw a case-control samples from a population with cases
affected and controls unaffected individuals. If single cases and
controls are given, individuals are drawn randomly from the whole
Population or from specified (virtual) subpopulations (parameter
subPops). Otherwise, a list of numbers should be used to specify
number of cases and controls from each subpopulation, which can be all
subpopulations if subPops=ALL_AVAIL (default), or from each of the
specified (virtual) subpopulations. This function returns a population with
all extracted individuals.
Function drawCaseControlSamples
-
simuPOP.sampling.drawCaseControlSamples(pop, cases, controls, numOfSamples=1, subPops=ALL_AVAIL)
- Draw numOfSamples case-control samples from a population with cases
affected and controls unaffected individuals and return a list of
populations. Please refer to function drawCaseControlSample for a
detailed descriptions of parameters.
class PedigreeSampler
-
class simuPOP.sampling.PedigreeSampler
The base class of all pedigree based sampler.
-
PedigreeSampler(families, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
Creates a pedigree sampler with parameters
- families
- number of families. This can be a number or a list of numbers. In
the latter case, specified families are drawn from each
subpopulation.
- subPops
- A list of (virtual) subpopulations from which samples are drawn.
The default value is ALL_AVAIL, which means all available
subpopulations of a population.
-
drawSample(input_pop)
- Randomly select Pedigrees
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
family(id)
- Get the family of individual with id.
-
prepareSample(pop, loci=[], infoFields=[], ancGens=True)
- Prepare self.pedigree, some pedigree sampler might need additional loci and
information fields for this sampler.
class AffectedSibpairSampler
-
class simuPOP.sampling.AffectedSibpairSampler
A sampler that draws a nuclear family with two affected offspring.
-
AffectedSibpairSampler(families, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- Initialize an affected sibpair sampler.
-
drawSample(input_pop)
- Randomly select Pedigrees
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
family(id)
- Return id, its spouse and their children
-
prepareSample(input_pop)
- Find the father or all affected sibpair families
Function drawAffectedSibpairSample
-
simuPOP.sampling.drawAffectedSibpairSample(pop, families, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- Draw affected sibpair samples from a population. If a single
families is given, affected sibpairs and their parents are drawn
randomly from the whole population or from specified (virtual)
subpopulations (parameter subPops). Otherwise, a list of numbers should
be used to specify number of families from each subpopulation, which can be
all subpopulations if subPops=ALL_AVAIL (default), or from each of the
specified (virtual) subpopulations. This function returns a population that
contains extracted individuals.
Function drawAffectedSibpairSamples
-
simuPOP.sampling.drawAffectedSibpairSamples(pop, families, numOfSamples=1, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- Draw numOfSamples affected sibpair samplesa from population pop and
return a list of populations. Please refer to function
drawAffectedSibpairSample for a description of other parameters.
class NuclearFamilySampler
-
class simuPOP.sampling.NuclearFamilySampler
A sampler that draws nuclear families with specified number of affected
parents and offspring.
-
NuclearFamilySampler(families, numOffspring, affectedParents=0, affectedOffspring=0, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
Creates a nuclear family sampler with parameters
- families
- number of families. This can be a number or a list of numbers. In the latter
case, specified families are drawn from each subpopulation.
- numOffspring
- number of offspring. This can be a fixed number or a range [min, max].
- affectedParents
- number of affected parents. This can be a fixed number or a range [min, max].
- affectedOffspring
- number of affected offspring. This can be a fixed number of a range [min, max].
- subPops
- A list of (virtual) subpopulations from which samples are drawn.
The default value is ALL_AVAIL, which means all available
subpopulations of a population.
-
drawSample(input_pop)
- Randomly select Pedigrees
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
family(id)
- Return id, its spouse and their children
-
prepareSample(input_pop)
Function drawNuclearFamilySample
-
simuPOP.sampling.drawNuclearFamilySample(pop, families, numOffspring, affectedParents=0, affectedOffspring=0, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- Draw nuclear families from a population. Number of offspring, number of
affected parents and number of affected offspring should be specified using
parameters numOffspring, affectedParents and affectedOffspring,
which can all be a single number, or a range [a, b] (b is incldued).
If a single families is given, Pedigrees are drawn randomly from the
whole population or from specified (virtual) subpopulations (parameter
subPops). Otherwise, a list of numbers should be used to specify
numbers of families from each subpopulation, which can be all
subpopulations if subPops=ALL_AVAIL (default), or from each of the
specified (virtual) subpopulations. This function returns a population that
contains extracted individuals.
Function drawNuclearFamilySamples
-
simuPOP.sampling.drawNuclearFamilySamples(pop, families, numOffspring, affectedParents=0, affectedOffspring=0, numOfSamples=1, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- Draw numOfSamples affected sibpair samplesa from population pop and
return a list of populations. Please refer to function
drawNuclearFamilySample for a description of other parameters.
class ThreeGenFamilySampler
-
class simuPOP.sampling.ThreeGenFamilySampler
A sampler that draws three-generation families with specified pedigree
size and number of affected individuals.
-
ThreeGenFamilySampler(families, numOffspring, pedSize, numOfAffected=0, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- families
- number of families. This can be a number or a list of numbers. In the latter
case, specified families are drawn from each subpopulation.
- numOffspring
- number of offspring. This can be a fixed number or a range [min, max].
- pedSize
- number of individuals in the Pedigree. This can be a fixed number or
a range [min, max].
- numAfffected
- number of affected individuals in the Pedigree. This can be a fixed number
or a range [min, max]
- subPops
- A list of (virtual) subpopulations from which samples are drawn.
The default value is ALL_AVAIL, which means all available
subpopulations of a population.
-
drawSample(input_pop)
- Randomly select Pedigrees
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
family(id)
- Return id, its spouse, their children, children’s spouse and grandchildren
-
prepareSample(input_pop)
Function drawThreeGenFamilySample
-
simuPOP.sampling.drawThreeGenFamilySample(pop, families, numOffspring, pedSize, numOfAffected=0, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- Draw three-generation families from a population. Such families consist
of grant parents, their children, spouse of these children, and grand
children. Number of offspring, total number of individuals, and total
number of affected individuals in a pedigree should be specified using
parameters numOffspring, pedSize and numOfAffected, which can all
be a single number, or a range [a, b] (b is incldued). If a single
families is given, Pedigrees are drawn randomly from the whole
Population or from specified (virtual) subpopulations (parameter
subPops). Otherwise, a list of numbers should be used to specify
numbers of families from each subpopulation, which can be all
subpopulations if subPops=ALL_AVAIL (default), or from each of the
specified (virtual) subpopulations. This function returns a population that
contains extracted individuals.
Function drawThreeGenFamilySamples
-
simuPOP.sampling.drawThreeGenFamilySamples(pop, families, numOffspring, pedSize, numOfAffected=0, numOfSamples=1, subPops=ALL_AVAIL, idField='ind_id', fatherField='father_id', motherField='mother_id')
- Draw numOfSamples three-generation pedigree samples from population pop
and return a list of populations. Please refer to function
drawThreeGenFamilySample for a description of other parameters.
class CombinedSampler
-
class simuPOP.sampling.CombinedSampler
A combined sampler accepts a list of sampler objects, draw samples and
combine the returned sample into a single population. An id field is
required to use this sampler, which will be used to remove extra copies of
individuals who have been drawn by different samplers.
-
CombinedSampler(samplers=[], idField='ind_id')
- samplers
- A list of samplers
-
drawSample(pop)
-
drawSamples(pop, numOfSamples)
- Draw multiple samples and return a list of populations.
-
prepareSample(pop, rearrange)
- Prepare passed population object for sampling according to parameter
subPops. If samples are drawn from the whole population, a
Population will be trimmed if only selected (virtual) subpopulations
are used. If samples are drawn separately from specified subpopulations,
Population pop will be rearranged (if rearrange==True) so that
each subpoulation corresponds to one element in parameter subPops.
Function drawCombinedSample
-
simuPOP.sampling.drawCombinedSample(pop, samplers, idField='ind_id')
- Draw different types of samples using a list of samplers. A
Population consists of all individuals from these samples will
be returned. An idField that stores an unique ID for all individuals
is needed to remove duplicated individuals who are drawn multiple
numOfSamples from these samplers.
Function drawCombinedSamples
-
simuPOP.sampling.drawCombinedSamples(pop, samplers, numOfSamples=1, idField='ind_id')
- Draw combined samples numOfSamples numOfSamples and return a list of populations.
Please refer to function drawCombinedSample for details about
parameters samplers and idField.