# API Reference

## Corpus Data

`read_chat`(path[, match, exclude, encoding]) | Read Cantonese CHAT data files.
`hkcancor`() | Create a corpus object for the Hong Kong Cantonese Corpus.
`CHATReader`() | A reader for Cantonese CHAT corpus files.
`CHATReader.search`(*[, onset, nucleus, coda, ...]) | Search the data for the given criteria.

## Jyutping Romanization

`characters_to_jyutping`(chars[, segmenter]) | Convert Cantonese characters into Jyutping romanization.
`parse_jyutping`(jp_str) | Parse Jyutping romanization into onset, nucleus, code, and tone.
`jyutping_to_yale`(jp_str[, as_list]) | Convert Jyutping romanization into Yale romanization.
`jyutping_to_tipa`(jp_str) | Convert Jyutping romanization into LaTeX TIPA.

## Natural Language Processing

`stop_words`([add, remove]) | Return Cantonese stop words.
`parse_text`(data, *[, segment_kwargs, ...]) | Parse raw Cantonese text.
`segment`(unsegmented[, cls]) | Segment the unsegmented input.
`word_segmentation.Segmenter`(*[, ...]) | A customizable word segmentation model.
`pos_tag`(words[, tagset]) | Tag the words for their parts of speech.
`pos_tagging.hkcancor_to_ud`([tag]) | Map a part-of-speech tag from HKCanCor to Universal Dependencies.

## `CHATReader`

class pycantonese.CHATReader

  A reader for Cantonese CHAT corpus files.

  Note

  Some of the methods are inherited from the parent class `Reader` for language acquisition, which may or may not be applicable to your use case.

  Methods

  `ages`([participant, months]) | Return the ages of the given participant in the data.
  `append`(reader) | Append data from another reader.
  `append_left`(reader) | Left-append data from another reader.
  `characters`([participants, exclude, ...]) | Return the data in individual Chinese characters.
  `clear`() | Remove all data from this reader.
  `dates_of_recording`([by_files]) | Return the dates of recording.
  `extend`(readers) | Extend data from other readers.
  `extend_left`(readers) | Left-extend data from other readers.
  `file_paths`() | Return the file paths.
  `filter`([match, exclude]) | Return a new reader filtered by file paths.
  `from_dir`(path[, match, exclude, extension, ...]) | Instantiate a reader from a local directory with CHAT data files.
  `from_files`(paths[, match, exclude, ...]) | Instantiate a reader from local CHAT data files.
  `from_strs`(strs[, ids, parallel]) | Instantiate a reader from in-memory CHAT data strings.
  `from_zip`(path[, match, exclude, extension, ...]) | Instantiate a reader from a local or remote ZIP file.
  `head`([n, participants, exclude]) | Return the first several utterances.
  `headers`() | Return the headers.
  `info`([verbose]) | Print a summary of this Reader's data.
  `ipsyn`() | (Not implemented - the upstream `ipsyn` method works for English only.)
  `jyutping`([participants, exclude, ...]) | Return the data in Jyutping romanization.
  `languages`([by_files]) | Return the languages in the data.
  `mlu`([participant]) | Return the mean lengths of utterance (MLU).
  `mlum`([participant]) | Return the mean lengths of utterance by morphemes.
  `mluw`([participant, exclude_switch]) | Return the mean lengths of utterance by words.
  `n_files`() | Return the number of files.
  `participants`([by_files]) | Return the participants (e.g., CHI, MOT).
  `pop`() | Drop the last data file from the reader and return it as a reader.
  `pop_left`() | Drop the first data file from the reader and return it as a reader.
  `search`(*[, onset, nucleus, coda, tone, ...]) | Search the data for the given criteria.
  `sents`([participants, exclude, by_files]) | Return the sents.
  `tagged_sents`([participants, exclude, by_files]) | Return the tagged sents.
  `tagged_words`([participants, exclude, by_files]) | Return the tagged words.
  `tail`([n, participants, exclude]) | Return the last several utterances.
  `to_chat`(path[, is_dir, filenames, tabular, ...]) | Export to CHAT data files.
  `to_strs`([tabular]) | Yield CHAT data strings.
  `tokens`([participants, exclude, ...]) | Return the tokens.
  `ttr`([keep_case, participant]) | Return the type-token ratios (TTR).
  `utterances`([participants, exclude, by_files]) | Return the utterances.
  `word_frequencies`([keep_case, participants, ...]) | Return word frequencies.
  `word_ngrams`(n[, keep_case, participants, ...]) | Return word ngrams.
  `words`([participants, exclude, ...]) | Return the words.

  character_sents |
  jyutping_sents |
  jyutpings |

  ages(participant='CHI', months=False) → Union[List[Tuple[int, int, int]], List[float]]

    Return the ages of the given participant in the data.

    Parameters
      participant str, optional

        Participant of interest, which defaults to the typical use case of `"CHI"` for the target child.

      months bool, optional

        If `False` (the default), age is represented as a tuple of (years, months, days), e.g., “1;06.00” in CHAT becomes `(1, 6, 0)`. If `True`, age is a float for the number of months, e.g., “1;06.00” in CHAT becomes `18.0` for 18 months.

    Returns
      List[Tuple[int, int, int]] if `months` is `False`, otherwise List[float]
  append(reader: pylangacq.chat.Reader) → None

    Append data from another reader.

    New data is appended as-is with no filtering of any sort, even for files whose file paths duplicate those already in the current reader.

    Parameters
      reader Reader

        A reader from which to append data

  append_left(reader: pylangacq.chat.Reader) → None

    Left-append data from another reader.

    New data is appended as-is with no filtering of any sort, even for files whose file paths duplicate those already in the current reader.

    Parameters
      reader Reader

        A reader from which to left-append data

  characters(participants=None, exclude=None, by_utterances=False, by_files=False) → Union[List[str], List[List[str]], List[List[List[str]]]]

    Return the data in individual Chinese characters.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_utterances bool, optional

        If `True`, the resulting objects are wrapped as a list at the utterance level. If `False` (the default), such utterance-level list structure does not exist.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[List[List[str]]] if both by_utterances and by_files are True
      List[List[str]] if by_utterances is True and by_files is False
      List[List[str]] if by_utterances is False and by_files is True
      List[str] if both by_utterances and by_files are False
  clear() → None

    Remove all data from this reader.

  dates_of_recording(by_files=False) → Union[Set[datetime.date], List[Set[datetime.date]]]

    Return the dates of recording.

    Parameters
      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      Set[datetime.date] if `by_files` is `False`,
      otherwise List[Set[datetime.date]]]
  extend(readers: Iterable[pylangacq.chat.Reader]) → None

    Extend data from other readers.

    New data is appended as-is with no filtering of any sort, even for files whose file paths duplicate those already in the current reader.

    Parameters
      readers Iterable[Reader]

        Readers from which to extend data

  extend_left(readers: Iterable[pylangacq.chat.Reader]) → None

    Left-extend data from other readers.

    New data is appended as-is with no filtering of any sort, even for files whose file paths duplicate those already in the current reader.

    Parameters
      readers Iterable[Reader]

        Readers from which to extend data

  file_paths() → List[str]

    Return the file paths.

    If the data comes from in-memory strings, then the “file paths” are arbitrary UUID random strings.

    Returns
      List[str]
  filter(match: str = None, exclude: str = None) → pylangacq.chat.Reader

    Return a new reader filtered by file paths.

    Parameters
      match str, optional

        If provided, only the file paths that match this string (by regular expression matching) are read and parsed. For example, to work with the American English dataset Brown (containing data for the children Adam, Eve, and Sarah), you can pass in `"Eve"` here to only handle the data for Eve, since the unzipped Brown data from CHILDES has a directory structure of `Brown/Eve/xxx.cha` for Eve’s data. If this parameter is not specified or `None` is passed in (the default), such file path filtering does not apply.

      exclude str, optional

        If provided, the file paths that match this string (by regular expression matching) are excluded for reading and parsing.

    Returns
      `pylangacq.Reader`
    Raises
      TypeError

        If neither `match` nor `exclude` is specified.

  classmethod from_dir(path: str, match: str = None, exclude: str = None, extension: str = '.cha', encoding: str = 'utf-8', parallel: bool = True) → pylangacq.chat.Reader

    Instantiate a reader from a local directory with CHAT data files.

    Parameters
      path str

        Local directory that contains CHAT data files. Files are searched for recursively under this directory, and those that satisfy `match` and `extension` are parsed and handled by the reader.

      match str, optional

        If provided, only the file paths that match this string (by regular expression matching) are read and parsed. For example, to work with the American English dataset Brown (containing data for the children Adam, Eve, and Sarah), you can pass in `"Eve"` here to only handle the data for Eve, since the unzipped Brown data from CHILDES has a directory structure of `Brown/Eve/xxx.cha` for Eve’s data. If this parameter is not specified or `None` is passed in (the default), such file path filtering does not apply.

      exclude str, optional

        If provided, the file paths that match this string (by regular expression matching) are excluded for reading and parsing.

      encoding str, optional

        Text encoding to parse the CHAT data. The default value is `"utf-8"` for Unicode UTF-8.

      extension str, optional

        File extension for CHAT data files. The default value is `".cha"`.

      parallel bool, optional

        If `True` (the default), CHAT reading and parsing is parallelized for speed-up, because in most cases multiple CHAT data files and/or strings are being handled. Under certain circumstances (e.g., your application is already parallelized and further parallelization from within PyLangAcq might be undesirable), you may like to consider setting this parameter to `False`.

    Returns
      `pylangacq.Reader`
  classmethod from_files(paths: List[str], match: str = None, exclude: str = None, encoding: str = 'utf-8', parallel: bool = True) → pylangacq.chat.Reader

    Instantiate a reader from local CHAT data files.

    Parameters
      paths List[str]

        List of local file paths of the CHAT data. The ordering of the paths determines that of the parsed CHAT data in the resulting reader.

      match str, optional

        If provided, only the file paths that match this string (by regular expression matching) are read and parsed. For example, to work with the American English dataset Brown (containing data for the children Adam, Eve, and Sarah), you can pass in `"Eve"` here to only handle the data for Eve, since the unzipped Brown data from CHILDES has a directory structure of `Brown/Eve/xxx.cha` for Eve’s data. If this parameter is not specified or `None` is passed in (the default), such file path filtering does not apply.

      exclude str, optional

        If provided, the file paths that match this string (by regular expression matching) are excluded for reading and parsing.

      encoding str, optional

        Text encoding to parse the CHAT data. The default value is `"utf-8"` for Unicode UTF-8.

      parallel bool, optional

        If `True` (the default), CHAT reading and parsing is parallelized for speed-up, because in most cases multiple CHAT data files and/or strings are being handled. Under certain circumstances (e.g., your application is already parallelized and further parallelization from within PyLangAcq might be undesirable), you may like to consider setting this parameter to `False`.

    Returns
      `pylangacq.Reader`
  classmethod from_strs(strs: List[str], ids: List[str] = None, parallel: bool = True) → pylangacq.chat.Reader

    Instantiate a reader from in-memory CHAT data strings.

    Parameters
      strs List[str]

        List of CHAT data strings. The ordering of the strings determines that of the parsed CHAT data in the resulting reader.

      ids List[str], optional

        List of identifiers. If not provided, UUID random strings are used. When file paths are referred to in other parts of this package, they mean these identifiers if you have instantiated the reader by this method.

      parallel bool, optional

        If `True` (the default), CHAT reading and parsing is parallelized for speed-up, because in most cases multiple CHAT data files and/or strings are being handled. Under certain circumstances (e.g., your application is already parallelized and further parallelization from within PyLangAcq might be undesirable), you may like to consider setting this parameter to `False`.

    Returns
      `pylangacq.Reader`
  classmethod from_zip(path: str, match: str = None, exclude: str = None, extension: str = '.cha', encoding: str = 'utf-8', parallel: bool = True, use_cached: bool = True, session: requests.sessions.Session = None) → pylangacq.chat.Reader

    Instantiate a reader from a local or remote ZIP file.

    If the input data is a remote ZIP file and you expect to call this method with the same path multiple times, consider downloading the data to the local system and then reading it from there to avoid unnecessary re-downloading. Caching a remote ZIP file isn’t implemented (yet) as the upstream CHILDES / TalkBank data is updated in minor ways from time to time.

    Parameters
      path str

        Either a local file path or a URL (one that begins with `"https://"` or `"http://"`) for a ZIP file containing CHAT data files. For instance, you can provide either a local path to a ZIP file downloaded from CHILDES, or simply a URL such as `"https://childes.talkbank.org/data/Eng-NA/Brown.zip"`.

      match str, optional

        If provided, only the file paths that match this string (by regular expression matching) are read and parsed. For example, to work with the American English dataset Brown (containing data for the children Adam, Eve, and Sarah), you can pass in `"Eve"` here to only handle the data for Eve, since the unzipped Brown data from CHILDES has a directory structure of `Brown/Eve/xxx.cha` for Eve’s data. If this parameter is not specified or `None` is passed in (the default), such file path filtering does not apply.

      exclude str, optional

        If provided, the file paths that match this string (by regular expression matching) are excluded for reading and parsing.

      encoding str, optional

        Text encoding to parse the CHAT data. The default value is `"utf-8"` for Unicode UTF-8.

      extension str, optional

        File extension for CHAT data files. The default value is `".cha"`.

      parallel bool, optional

        If `True` (the default), CHAT reading and parsing is parallelized for speed-up, because in most cases multiple CHAT data files and/or strings are being handled. Under certain circumstances (e.g., your application is already parallelized and further parallelization from within PyLangAcq might be undesirable), you may like to consider setting this parameter to `False`.

      use_cached bool, optional

        If `True` (the default), and if the path is a URL for a remote ZIP archive, then CHAT reading attempts to use the previously downloaded data cached on disk. This setting allows you to call this function with the same URL repeatedly without hitting the CHILDES / TalkBank server more than once for the same data. Pass in `False` to force a new download; the upstream CHILDES / TalkBank data is updated in minor ways from time to time, e.g., for CHAT format, header/metadata information, updated annotations. See also the helper functions: `pylangacq.chat.cached_data_info()`, `pylangacq.chat.remove_cached_data()`.

      session requests.Session, optional

        If the path is a URL for a remote ZIP archive, data downloading is done with reasonable settings of retries and timeout by default, in order to be robust against intermittent network issues. If necessary, pass in your own instance of `requests.Session` to customize.

    Returns
      `pylangacq.Reader`
  head(n: int = 5, participants=None, exclude=None)

    Return the first several utterances.

    Parameters
      n int, optional

        The number of utterances to return.

      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

    Returns
      list of utterances
  headers() → List[Dict]

    Return the headers.

    Returns
      List[Dict]
  info(verbose=False) → None

    Print a summary of this Reader’s data.

    Parameters
      verbose bool, optional

        If `True` (default is `False`), show the details of all the files.

  ipsyn()

    (Not implemented - the upstream `ipsyn` method works for English only.)

  jyutping(participants=None, exclude=None, by_utterances=False, by_files=False) → Union[List[str], List[List[str]], List[List[List[str]]]]

    Return the data in Jyutping romanization.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_utterances bool, optional

        If `True`, the resulting objects are wrapped as a list at the utterance level. If `False` (the default), such utterance-level list structure does not exist.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[List[List[str]]] if both by_utterances and by_files are True
      List[List[str]] if by_utterances is True and by_files is False
      List[List[str]] if by_utterances is False and by_files is True
      List[str] if both by_utterances and by_files are False
  languages(by_files=False) → Union[Set[str], List[List[str]]]

    Return the languages in the data.

    Parameters
      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      Set[str] if `by_files` is `False`, otherwise List[List[str]]

        When `by_files` is `True`, the ordering of languages given by the list indicates language dominance. Such ordering would not make sense when `by_files` is `False`, in which case the returned object is a set instead of a list.

  mlu(participant='CHI') → List[float]

    Return the mean lengths of utterance (MLU).

    This method is equivalent to `mlum()`.

    Parameters
      participant str, optional

        Participant of interest, which defaults to the typical use case of `"CHI"` for the target child.

    Returns
      List[float]
  mlum(participant='CHI') → List[float]

    Return the mean lengths of utterance by morphemes.

    Parameters
      participant str, optional

        Participant of interest, which defaults to the typical use case of `"CHI"` for the target child.

    Returns
      List[float]
  mluw(participant='CHI', exclude_switch: bool = False) → List[float]

    Return the mean lengths of utterance by words.

    Parameters
      participant str, optional

        Participant of interest, which defaults to the typical use case of `"CHI"` for the target child.

      exclude_switch bool, optional

        If `True`, words with the suffix “@s” for switching to another language (not uncommon in code-mixing or multilingual acquisition) are excluded. The default is `False`.

    Returns
      List[float]
  n_files() → int

    Return the number of files.

  participants(by_files=False) → Union[Set[str], List[Set[str]]]

    Return the participants (e.g., CHI, MOT).

    Parameters
      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      Set[str] if `by_files` is `False`, otherwise List[Set[str]]
  pop() → pylangacq.chat.Reader

    Drop the last data file from the reader and return it as a reader.

    Returns
      `pylangacq.Reader`
  pop_left() → pylangacq.chat.Reader

    Drop the first data file from the reader and return it as a reader.

    Returns
      `pylangacq.Reader`
  search(*, onset=None, nucleus=None, coda=None, tone=None, initial=None, final=None, jyutping=None, character=None, pos=None, word_range=(0, 0), utterance_range=(0, 0), sent_range=(0, 0), by_tokens=True, by_utterances=False, tagged=None, sents=None, participants=None, exclude=None, by_files=False)

    Search the data for the given criteria.

    For examples, please see https://pycantonese.org/searches.html.

    Parameters
      onset str, optional

        Onset to search for. A regex is supported.

      nucleus str, optional

        Nucleus to search for. A regex is supported.

      coda str, optional

        Coda to search for. A regex is supported.

      tone str, optional

        Tone to search for. A regex is supported.

      initial str, optional

        Initial to search for. A regex is supported. An initial, a term more prevalent in traditional Chinese phonology, is the equivalent of an onset.

      final str, optional

        Final to search for. A final, a term more prevalent in traditional Chinese phonology, is the equivalent of a nucleus plus a coda.

      jyutping str, optional

        Jyutping romanization of one Cantonese character to search for. If the romanization contains more than one character, a ValueError is raised.

      character str, optional

        One or more Cantonese characters (within a segmented word) to search for.

      pos str, optional

        A part-of-speech tag to search for. A regex is supported.

      word_range tuple[int, int], optional

        Span of words to the left and right of a matching word to include in the output. The default is (0, 0) to disable a range. If sent_range is used, word_range is ignored.

      utterance_range Tuple[int, int], optional

        Span of utterances before and after an utterance containing a matching word to include in the output. If set to `(0, 0)` (the default), no utterance range output is generated. If utterance_range is used, word_range is ignored.

      sent_range Tuple[int, int], optional

        [Deprecated; please use utterance_range instead]

      by_tokens bool, optional

        If `True` (the default), words in the output are in the token form (i.e., with Jyutping and part-of-speech tags). Otherwise just words as text strings are returned.

      by_utterances bool, optional

        If `True` (default is False), utterances containing matching words are returned. Otherwise, only matching words are returned.

      tagged bool, optional

        [Deprecated; please use by_tokens instead]

      sents bool, optional

        [Deprecated; please use by_utterances instead]

      participants str or iterable[str], optional

        One or more participants to include in the search. If unspecified, all participants are included.

      exclude str or iterable[str], optional

        One or more participants to exclude in the search. If unspecified, no participants are excluded.

      by_files bool, optional

        If True (default: False), return data organized by the individual file paths.

    Returns
      list
  sents(participants=None, exclude=None, by_files=False) → Union[List[List[str]], List[List[List[str]]]]

    Return the sents.

    Deprecated since version 0.13.0: Please use `words()` with `by_utterances=True` instead.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[List[str]] if `by_files` is `False`, otherwise List[List[List[str]]]
  tagged_sents(participants=None, exclude=None, by_files=False) → Union[List[List[pylangacq.objects.Token]], List[List[List[pylangacq.objects.Token]]]]

    Return the tagged sents.

    Deprecated since version 0.13.0: Please use `tokens()` with `by_utterances=True` instead.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[List[Token]] if `by_files` is `False`,
      otherwise List[List[List[Token]]]
  tagged_words(participants=None, exclude=None, by_files=False) → Union[List[pylangacq.objects.Token], List[List[pylangacq.objects.Token]]]

    Return the tagged words.

    Deprecated since version 0.13.0: Please use `tokens()` with `by_utterances=False` instead.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[Token] if `by_files` is `False`, otherwise List[List[Token]]
  tail(n: int = 5, participants=None, exclude=None)

    Return the last several utterances.

    Parameters
      n int, optional

        The number of utterances to return.

      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

    Returns
      list of utterances
  to_chat(path: str, is_dir: bool = False, filenames: Optional[Iterable[str]] = None, tabular: bool = True, encoding: str = 'utf-8') → None

    Export to CHAT data files.

    Parameters
      path str

        The path to a file where you want to output the CHAT data, e.g., “data.cha”, “foo/bar/data.cha”.

      is_dir bool, optional

        If `True` (default is `False`), then `path` is interpreted as a directory instead. The CHAT data is written to possibly multiple files under this directory. The number of files you get can be checked by calling `n_files()`, which depends on how this reader object is created.

      filenames Iterable[str], optional

        Used only when `is_dir` is `True`. These are the filenames of the CHAT files to write. If `None` or not given, {0001.cha, 0002.cha, …} are used.

      tabular bool, optional

        If `True`, adjust spacing such that the three tiers of the utterance, %mor, and %gra are aligned in a tabular form. Note that such alignment would drop annotations (e.g., pauses) on the main utterance tier.

      encoding str, optional

        Text encoding to output the CHAT data as. The default value is `"utf-8"` for Unicode UTF-8.

    Raises
      ValueError

        - If you attempt to output data to a single local file, but the CHAT data in this reader appears to be organized in multiple files.

        - If you attempt to output data to a directory while providing your own filenames, but the number of your filenames doesn’t match the number of CHAT files in this reader object.

  to_strs(tabular: bool = True) → Generator[str, None, None]

    Yield CHAT data strings.

    Note

    The header information may not be completely reproduced in the output CHAT strings. Known issues all have to do with a header field used multiple times in the original CHAT data. For `Date`, only the first date of recording is retained in the output string. For all other multiply used header fields (e.g., `Tape Location`, `Time Duration`), only the last value in a given CHAT file is retained. Note that `ID` for participant information is not affected.

    Parameters
      tabular bool, optional

        If `True`, adjust spacing such that the three tiers of the utterance, %mor, and %gra are aligned in a tabular form. Note that such alignment would drop annotations (e.g., pauses) on the main utterance tier.

    Yields
      str

        CHAT data string for one file.

  tokens(participants=None, exclude=None, by_utterances=False, by_files=False) → Union[List[pylangacq.objects.Token], List[List[pylangacq.objects.Token]], List[List[List[pylangacq.objects.Token]]]]

    Return the tokens.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_utterances bool, optional

        If `True`, the resulting objects are wrapped as a list at the utterance level. If `False` (the default), such utterance-level list structure does not exist.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[List[List[Token]]] if both `by_utterances` and `by_files` are `True`
      List[List[Token]] if `by_utterances` is `True` and `by_files` is `False`
      List[List[Token]] if `by_utterances` is `False` and `by_files` is `True`
      List[Token] if both `by_utterances` and `by_files` are `False`
  ttr(keep_case=True, participant='CHI') → List[float]

    Return the type-token ratios (TTR).

    Parameters
      keep_case bool, optional

        If `True` (the default), case distinctions are kept, e.g., word tokens like “the” and “The” are treated as distinct. If `False`, all word tokens are forced to be in lowercase as a preprocessing step. CHAT data from CHILDES intentionally does not follow the orthographic convention of capitalizing the first letter of a sentence in the transcriptions (as would have been done in many European languages), and so leaving keep_case as True is appropriate in most cases.

      participant str, optional

        Participant of interest, which defaults to the typical use case of `"CHI"` for the target child.

    Returns
      List[float]
  utterances(participants=None, exclude=None, by_files=False) → Union[List[pylangacq.objects.Utterance], List[List[pylangacq.objects.Utterance]]]

    Return the utterances.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[Utterance] if `by_files` is `False`, otherwise List[List[Utterance]]
  word_frequencies(keep_case=True, participants=None, exclude=None, by_files=False) → Union[collections.Counter, List[collections.Counter]]

    Return word frequencies.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

      keep_case bool, optional

        If `True` (the default), case distinctions are kept, e.g., word tokens like “the” and “The” are treated as distinct. If `False`, all word tokens are forced to be in lowercase as a preprocessing step. CHAT data from CHILDES intentionally does not follow the orthographic convention of capitalizing the first letter of a sentence in the transcriptions (as would have been done in many European languages), and so leaving keep_case as True is appropriate in most cases.

    Returns
      collections.Counter if `by_files` is `False`,
      otherwise List[collections.Counter]
  word_ngrams(n, keep_case=True, participants=None, exclude=None, by_files=False) → Union[collections.Counter, List[collections.Counter]]

    Return word ngrams.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

      keep_case bool, optional

        If `True` (the default), case distinctions are kept, e.g., word tokens like “the” and “The” are treated as distinct. If `False`, all word tokens are forced to be in lowercase as a preprocessing step. CHAT data from CHILDES intentionally does not follow the orthographic convention of capitalizing the first letter of a sentence in the transcriptions (as would have been done in many European languages), and so leaving keep_case as True is appropriate in most cases.

    Returns
      collections.Counter if `by_files` is `False`,
      otherwise List[collections.Counter]
  words(participants=None, exclude=None, by_utterances=False, by_files=False) → Union[List[str], List[List[str]], List[List[List[str]]]]

    Return the words.

    Parameters
      participants str or iterable of str, optional

        Participants of interest. You may pass in a string (e.g., `"CHI"` for studying child speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are included. If you pass in `None` (the default), all participants are included. This parameter cannot be used together with `exclude`.

      exclude str or iterable of str, optional

        Participants to exclude. You may pass in a string (e.g., `"CHI"` for child-directed speech) or an iterable of strings (e.g., `{"MOT", "INV"}`). Only the specified participants are excluded. If you pass in `None` (the default), no participants are excluded. This parameter cannot be used together with `participants`.

      by_utterances bool, optional

        If `True`, the resulting objects are wrapped as a list at the utterance level. If `False` (the default), such utterance-level list structure does not exist.

      by_files bool, optional

        If `True`, return a list X of results, where len(X) is the number of files in the `Reader` object, and each element in X is the result for one file; the ordering of X corresponds to that of the file paths from `file_paths()`. If `False` (the default), return the result that collapses the file distinction just described for when `by_files` is `True`.

    Returns
      List[List[List[str]]] if both `by_utterances` and `by_files` are `True`
      List[List[str]] if `by_utterances` is `True` and `by_files` is `False`
      List[List[str]] if `by_utterances` is `False` and `by_files` is `True`
      List[str] if both `by_utterances` and `by_files` are `False`

## `Token`

class pycantonese.corpus.Token(word: str, pos: Optional[str], jyutping: Optional[str], mor: Optional[str], gloss: Optional[str], gra: Optional[pylangacq.objects.Gra])

  Token with attributes as parsed from a CHAT utterance.

  Attributes
    word str

      Word form of the token

    pos str

      Part-of-speech tag

    jyutping str

      Jyutping romanization

    mor str

      Morphological information

    gloss str

      Gloss in English

    gra Gra

      Grammatical relation

  Methods

  to_gra_tier |
  to_mor_tier |

## `Jyutping`

class pycantonese.jyutping.Jyutping(onset: str, nucleus: str, coda: str, tone: str)

  Jyutping representation of a Chinese/Cantonese character.

  Attributes
    onset str

      Onset

    nucleus str

      Nucleus

    coda str

      Coda

    tone str

      Tone

  __eq__(other)

    Return self==value.

  __hash__ = None
  __init__(onset: str, nucleus: str, coda: str, tone: str) → None
  __repr__()

    Return repr(self).

  __str__()

    Combine onset + nucleus + coda + tone.

  property final

    Return the final (= nucleus + coda).