`nimare.studyset`.Studyset

class Studyset(source, target='mni152_2mm', mask=None, annotations=None, basepath=None)[source]

Bases: object

A collection of studies for meta-analysis.

Parameters:

source (dict, str, or StudysetStore) – A NIMADS studyset dictionary, a path to one as JSON, a path to a parquet release directory, or an existing store.
target (str or None, default=”mni152_2mm”) – Space to report coordinates in. The raw coordinates are always kept, so re-targeting is exact rather than cumulative.
mask (Niimg-like or NiftiMasker, optional) – Masker for execution. Defaults to the template brain mask for target.
annotations (list of dict, optional) – Extra NIMADS annotation payloads to attach.
basepath (str, optional) – Directory that relative image paths are resolved against.

Methods

`combine_analyses`()	One analysis per study, foci and images concatenated.
`coordinate_block`()	Return the foci for the selection, grouped by analysis.
`copy`()	Return a new handle on the same immutable store.
`exclude_study_ids`(study_ids)	Return a studyset without the requested studies.
`filter_annotations`(labels[, threshold, ...])	Keep analyses whose annotation labels reach `threshold`.
`filter_ids`(ids)	Keep the named analyses, by full id or short analysis id.
`filter_metadata`(field, op, value)	Keep analyses whose metadata `field` satisfies `op value`.
`filter_study_ids`(study_ids)	Return a studyset with only the requested studies.
`from_dataset`(dataset)	Convert a legacy `Dataset`.
`from_nimads`(source, **kwargs)	Read a NIMADS studyset from a dict or a JSON path.
`from_parquet`(directory, **kwargs)	Read a parquet studyset release directory.
`from_sleuth`(sleuth_file, **kwargs)	Read a Sleuth text file.
`get_analyses_by_annotations`(key[, value])	Analyses carrying `key`, which may name a label or a whole annotation.
`get_analyses_by_coordinate`(xyz[, r, n])	Short analysis ids near `xyz`, by radius or by count.
`get_analyses_by_label`([labels, ...])	Short analysis ids whose labels reach the threshold.
`get_analyses_by_mask`(mask)	Short analysis ids with at least one focus inside `mask`.
`get_analyses_by_metadata`(key[, value])	`{analysis id: {key: value}}` for analyses carrying `key`.
`get_annotations`([analyses])	`{analysis id: {label: value}}`, merged across every annotation.
`get_images`([imtype, ids, policy])	Image types present, or one type's paths.
`get_labels`([ids])	Labels present in the studyset's annotations.
`get_metadata`([field, ids])	Metadata field names, or one field's values.
`get_points`([analyses])	`{analysis id: [point dicts]}`.
`get_studies_by_coordinate`(xyz[, r])	Full analysis ids with a focus within `r` mm of any of `xyz`.
`get_studies_by_label`([labels, ...])	Full analysis ids whose labels reach the threshold.
`get_studies_by_mask`(mask)	Full analysis ids with at least one focus inside `mask`.
`get_texts`([text_type, ids])	Text field names, or one field's values.
`harmonized`(target)	Return a studyset whose stored coordinates are in `target`.
`image_block`(imtype, *[, policy])	Return the images of one type for the selection.
`keep_images`(image_mask)	Return a studyset holding only the flagged images.
`label_block`([annotation])	Return the annotation matrix for the selection.
`load`(filename)	Load a pickled studyset.
`materialize_points`()	Return a studyset whose store holds only the currently selected foci.
`merge`(right)	Merge another studyset in, preferring this one on conflicts.
`resolve`(requirements_[, drop_invalid])	Narrow to the analyses that satisfy every requirement, and build blocks.
`row_of_id`()	Return `{analysis id: row in this studyset}`, memoised.
`sample_sizes`([reduce])	One sample size per analysis, from whichever level declares it.
`save`(filename)	Pickle the studyset.
`select_analyses`(mask)	Keep the analyses a boolean mask -- or an array of positions -- selects.
`select_points`(point_mask)	Keep a subset of foci and every analysis.
`slice`([ids, analyses, filter_level])	Return a studyset with only the requested ids.
`text_block`([field])	Return one text field for the selection.
`to_dataset`()	Convert to a legacy `Dataset`.
`to_dict`()	Build the nested NIMADS document for the selected analyses.
`to_nimads`(filename)	Write NIMADS JSON.
`to_parquet`(directory)	Write a parquet studyset release directory.
`update_path`(new_path)	Resolve relative image paths against `new_path`.
`with_annotation`(name, labels, matrix[, ...])	Return a studyset carrying an extra annotation.
`with_annotation_payload`(payload)	Return a studyset carrying a NIMADS annotation payload.
`with_annotations_df`(frame[, name, replace])	Return a studyset carrying `frame` as an annotation.
`with_context`(**changes)	Return a studyset with different space, masker or basepath.
`with_images`(analysis_positions, refs, ...)	Return a studyset with extra images.
`with_metadata`(name, values, *[, level])	Return a studyset with one extra metadata column.
`with_points`(analysis_positions, xyz, **kwargs)	Return a studyset with extra foci.
`with_texts`(rows, field, values)	Return a studyset with text added.

Properties

`analyses`	Read-only nested accessors for the selected analyses.
`annotations`	`list` of `AnnotationSet`.
`annotations_df`	Every annotation flattened into one frame.
`basepath`	Return the directory relative image paths resolve against.
`coordinates`	One row per focus.
`id`	Return the studyset id.
`ids`	full `study-analysis` identifiers.
`image_rows`	One row per stored image.
`images`	One row per analysis, one column per image type.
`masker`	Return the masker images are sampled onto.
`metadata`	One row per analysis, study metadata merged in.
`name`	Return the studyset name.
`space`	Return the space coordinates are reported in.
`store`	The immutable store behind this studyset.
`studies`	Read-only nested accessors for the selected studies.
`study_ids`	unique study identifiers.
`texts`	Return one row per analysis of the text fields.
`view`	The selection over that store.

property analyses: Read-only nested accessors for the selected analyses.

property annotations: list of AnnotationSet.

property annotations_df

Every annotation flattened into one frame.

Collisions between annotations are qualified with the annotation id and recorded in frame.attrs["annotation_collisions"] rather than one silently overwriting the other.

property basepath: Return the directory relative image paths resolve against.

combine_analyses()[source]

One analysis per study, foci and images concatenated.

Annotation notes name pre-merge analyses, so they cannot be carried over and are dropped.

coordinate_block()[source]: Return the foci for the selection, grouped by analysis.

property coordinates: One row per focus.

copy()[source]: Return a new handle on the same immutable store.

exclude_study_ids(study_ids)[source]

Return a studyset without the requested studies.

An id matching nothing is not an error.

filter_annotations(labels, threshold=0.001, match='all', annotation=None)[source]: Keep analyses whose annotation labels reach threshold.

filter_ids(ids)[source]

Keep the named analyses, by full id or short analysis id.

Raises ValueError naming any id that matches nothing.

filter_metadata(field, op, value)[source]: Keep analyses whose metadata field satisfies op value.

filter_study_ids(study_ids)[source]

Return a studyset with only the requested studies.

Raises ValueError naming any id that matches nothing.

classmethod from_dataset(dataset)[source]

Convert a legacy Dataset.

Not optimised: Dataset is deprecated, and this is the boundary where it becomes a studyset before anything else touches it.

classmethod from_nimads(source, **kwargs)[source]: Read a NIMADS studyset from a dict or a JSON path.

classmethod from_parquet(directory, **kwargs)[source]: Read a parquet studyset release directory.

classmethod from_sleuth(sleuth_file, **kwargs)[source]: Read a Sleuth text file.

get_analyses_by_annotations(key, value=None)[source]

Analyses carrying key, which may name a label or a whole annotation.

Accepts either form: the previous implementation keyed on the annotation id here while get_studies_by_label keyed on the label.

get_analyses_by_coordinate(xyz, r=None, n=None)[source]: Short analysis ids near xyz, by radius or by count.

get_analyses_by_label(labels=None, label_threshold=0.001, annotation=None)[source]: Short analysis ids whose labels reach the threshold.

get_analyses_by_mask(mask)[source]: Short analysis ids with at least one focus inside mask.

get_analyses_by_metadata(key, value=None)[source]: {analysis id: {key: value}} for analyses carrying key.

get_annotations(analyses=None)[source]: {analysis id: {label: value}}, merged across every annotation.

get_images(imtype=None, ids=None, policy='first')[source]: Image types present, or one type’s paths.

get_labels(ids=None)[source]: Labels present in the studyset’s annotations.

get_metadata(field=None, ids=None)[source]: Metadata field names, or one field’s values.

get_points(analyses=None)[source]: {analysis id: [point dicts]}.

get_studies_by_coordinate(xyz, r=20)[source]: Full analysis ids with a focus within r mm of any of xyz.

get_studies_by_label(labels=None, label_threshold=0.001, annotation=None)[source]: Full analysis ids whose labels reach the threshold.

get_studies_by_mask(mask)[source]: Full analysis ids with at least one focus inside mask.

get_texts(text_type=None, ids=None)[source]: Text field names, or one field’s values.

harmonized(target)[source]: Return a studyset whose stored coordinates are in target.

property id: Return the studyset id.

property ids

full study-analysis identifiers.

Type:: numpy.ndarray

image_block(imtype, *, policy='all')[source]: Return the images of one type for the selection.

property image_rows: One row per stored image. The shape an image mask is aligned to.

property images: One row per analysis, one column per image type.

keep_images(image_mask)[source]

Return a studyset holding only the flagged images. Copy-on-write.

image_mask is a boolean aligned to the rows of image_rows, so a predicate over that frame selects directly:

studyset.keep_images(studyset.image_rows["id"] != "study-1")

Note that images is the wide frame – one row per analysis, one column per type – so it is not the right thing to mask against. Foci are untouched, so a point selection made earlier stays valid.

label_block(annotation=None)[source]: Return the annotation matrix for the selection.

static load(filename)[source]: Load a pickled studyset.

property masker: Return the masker images are sampled onto.

materialize_points()[source]: Return a studyset whose store holds only the currently selected foci.

merge(right)[source]: Merge another studyset in, preferring this one on conflicts.

property metadata: One row per analysis, study metadata merged in.

property name: Return the studyset name.

resolve(requirements_, drop_invalid=True)[source]: Narrow to the analyses that satisfy every requirement, and build blocks.

row_of_id()[source]: Return {analysis id: row in this studyset}, memoised.

sample_sizes(reduce='mean')[source]: One sample size per analysis, from whichever level declares it.

save(filename)[source]: Pickle the studyset.

select_analyses(mask)[source]: Keep the analyses a boolean mask – or an array of positions – selects.

select_points(point_mask)[source]: Keep a subset of foci and every analysis.

slice(ids=None, *, analyses=None, filter_level='analysis')[source]

Return a studyset with only the requested ids.

Changed in version 0.21.0: An id naming nothing raises instead of being ignored.

Parameters:

ids (str or array_like of str) – Analysis ids, or study ids when filter_level="study". An analysis may be named by its full "<study id>-<analysis id>" id, which ids lists, or by its analysis id alone. A short id shared by several analyses selects all of them.
analyses (array_like of str, optional) – An alias for ids.
filter_level ({"analysis", "study"}, default="analysis") – Which level ids names.

Returns:

A studyset holding only the named analyses.

Return type:

Studyset

Raises:

ValueError – If any id names nothing in this studyset, naming the ids that failed. An empty ids is not an error.

property space: Return the space coordinates are reported in.

property store: The immutable store behind this studyset.

property studies

Read-only nested accessors for the selected studies.

Views over the columns rather than a second copy of the data, so reading them cannot drift from what the store holds.

property study_ids

unique study identifiers.

Type:: numpy.ndarray

text_block(field='abstract')[source]: Return one text field for the selection.

property texts: Return one row per analysis of the text fields.

to_dataset()[source]

Convert to a legacy Dataset.

Not optimised: Dataset is deprecated and this exists so that existing data can still be written out.

to_dict()[source]: Build the nested NIMADS document for the selected analyses.

to_nimads(filename)[source]: Write NIMADS JSON.

to_parquet(directory)[source]: Write a parquet studyset release directory.

update_path(new_path)[source]: Resolve relative image paths against new_path.

property view: The selection over that store.

with_annotation(name, labels, matrix, rows=None, note_key_types=None)[source]: Return a studyset carrying an extra annotation. Copy-on-write.

with_annotation_payload(payload)[source]: Return a studyset carrying a NIMADS annotation payload. Copy-on-write.

with_annotations_df(frame, name=None, replace=False)[source]

Return a studyset carrying frame as an annotation. Copy-on-write.

The write counterpart of annotations_df: a frame with an id column and one column per label. replace=True discards the existing annotations, which is what a caller who round-tripped annotations_df means.