collections.volume

Volume

Bases: SlottedDict[Paper]

A publication volume.

Provides dictionary-like functionality mapping paper IDs to Paper objects in the volume.

Info

To create a new volume, use Collection.create_volume().

Required Attributes:

Name	Type	Description
id	str	The ID of this volume (e.g. "1" or "main").
parent	Collection	The collection this volume belongs to.
type	VolumeType	Value indicating the type of publication, e.g., journal or conference proceedings.
title	MarkupText	The title of the volume. (Aliased to booktitle for initialization.)
year	str	The year of publication.

Tuple Attributes:

Name	Type	Description
editors	tuple[NameSpecification, ...]	Names of editors associated with this volume.
sig_ids	tuple[str, ...]	List of SIG IDs associated with this volume. See also sigs/add_sig/remove_sig.
venue_ids	tuple[str, ...]	List of venue IDs associated with this volume. See also venues/add_venue/remove_venue.
urls	tuple[tuple[str, URLReference], ...]	Links to external, non-locally-hosted resources associated with this volume (e.g. supplementary materials), as tuples of (type_of_link, reference); can be empty.

Optional Attributes:

Name	Type	Description
address	Optional[str]	The publisher's address for this volume.
doi	Optional[str]	The DOI for the volume.
isbn	Optional[str]	The ISBN for the volume.
journal_issue	Optional[str]	The journal's issue number, if this volume belongs to a journal.
journal_volume	Optional[str]	The journal's volume number, if this volume belongs to a journal.
journal_title	Optional[str]	The journal's title (without volume/issue/subtitle), if this volume belongs to a journal.
month	Optional[str]	The month of publication.
pdf	Optional[PDFReference]	A reference to the volume's PDF.
publisher	Optional[str]	The volume's publisher.
shorttitle	Optional[MarkupText]	A shortened form of the title. (Aliased to shortbooktitle for initialization.)

collection property

collection

The collection this volume belongs to.

collection_id property

collection_id

The collection ID this volume belongs to.

frontmatter property

frontmatter

Returns the volume's frontmatter, if any.

full_id property

full_id

The full anthology ID of this volume (e.g. "L06-1" or "2022.emnlp-main").

full_id_tuple property

full_id_tuple

The full anthology ID of this volume, as a tuple (e.g. ("L06", "1", None)).

has_abstracts property

has_abstracts

True if at least one paper in this volume has an abstract.

has_frontmatter property

has_frontmatter

True if this volume has frontmatter.

ingest_date property writable

ingest_date

The date when this volume was added to the Anthology. If not set explicitly, will use constants.UNKNOWN_INGEST_DATE instead.

is_workshop property

is_workshop

True if this volume is a workshop proceedings.

journal_title property writable

journal_title

The journal title for this volume. Fetched from the associated venue if not explicitly set.

namespecs property

namespecs

All name specifications on this volume.

pdf property writable

pdf

A reference to the volume's PDF.

<pdf> always refers to a local file, so the reference's name is derived from this volume's full_id rather than stored -- it is not present in the XML.

root property

root

The Anthology instance to which this object belongs.

venue_acronym property

venue_acronym

The acronym of the venue(s) associated with this volume. In case of multiple venues, this will be a concatenation of the individual venue acronyms.

web_url property

web_url

The URL of this volume's landing page on the ACL Anthology website.

add_sig

add_sig(sig)

Associate a SIG with this volume.

If the SIG is already associated with this volume, this will do nothing.

Parameters:

Name	Type	Description	Default
sig	str | SIG	A SIG object, or a string representing a SIG ID.	required

Raises:

Type	Description
ValueError	If a string was given, but the SIG does not exist.

add_venue

add_venue(venue)

Associate a venue with this volume.

If the venue is already associated with this volume, this will do nothing.

Parameters:

Name	Type	Description	Default
venue	str | Venue	A Venue object, or a string representing a venue ID.	required

Raises:

Type	Description
ValueError	If a string was given, but the venue does not exist.

create_paper

create_paper(title, id=None, bibkey=NO_BIBKEY, **kwargs)

Create a new Paper object in this volume.

Parameters:

Name	Type	Description	Default
title	MarkupText | str	The title of the new paper. If given as a string, it will be heuristically parsed for markup.	required
id	Optional[str]	The ID of the new paper (optional); if None, will generate the next-highest numeric ID that doesn't already exist in this volume.	None
bibkey	str	The citation key of the new paper (optional); defaults to constants.NO_BIBKEY, in which case a non-clashing citation key will be automatically generated (recommended!).	NO_BIBKEY
**kwargs	Any	Any valid list or optional attribute of Paper.	{}

Returns:

Type	Description
Paper	The created Paper object.

Raises:

Type	Description
AnthologyDuplicateIDError	If a paper with the given ID or bibkey already exists.

from_xml classmethod

from_xml(parent, meta)

Instantiates a new volume from its <meta> block in the XML.

generate_paper_id

generate_paper_id()

Generate a paper ID that is not yet taken in this volume.

This will always generate a numeric ID that is one higher than the currently highest numeric ID in this volume. If the volume is empty, it will return "1".

Returns:

Type	Description
str	A paper ID not yet taken in this volume.

get_events

get_events()

Returns:

Type	Description
list[Event]	A list of events associated with this volume.

get_namespec_for

get_namespec_for(person)

Find the NameSpecification on this volume that refers to a given Person.

Parameters:

Name	Type	Description	Default
person	Person	A person that is an editor on this volume.	required

Returns:

Type	Description
NameSpecification	The NameSpecification that resolves to the given Person.

Raises:

Type	Description
ValueError	If none of the editors resolve to the given Person.

papers

papers()

An iterator over all Paper objects in this volume.

remove_sig

remove_sig(sig)

Remove a SIG association from this volume.

If the SIG is not associated with this volume, this will do nothing.

Parameters:

Name	Type	Description	Default
sig	str | SIG	A SIG object, or a string representing a SIG ID.	required

remove_venue

remove_venue(venue)

Remove a venue association from this volume.

If the venue is not associated with this volume, this will do nothing.

Parameters:

Name	Type	Description	Default
venue	str | Venue	A Venue object, or a string representing a venue ID.	required

sigs

sigs()

Returns:

Type	Description
list[SIG]	A list of SIGs associated with this volume.

to_bibtex

to_bibtex()

Generate a BibTeX entry for this volume.

Returns:

Type	Description
str	The BibTeX entry for this volume as a formatted string. Currently, this is simply the frontmatter's BibTeX.

Raises:

Type	Description
Exception	If this volume has no frontmatter.

to_xml

to_xml(with_papers=True)

Serialize this volume in the Anthology XML format.

Parameters:

Name	Type	Description	Default
with_papers	bool	If False, the returned <volume> will only contain the volume's <meta> block, but no contained papers. Defaults to True.	True

Returns:

Type	Description
_Element	A serialization of this volume as a <volume> block in the Anthology XML format.

venues

venues()

A list of venues associated with this volume.